API
Folium Sheet API reference documentation
APIs
When using Folium Sheet you have two APIS that you can use:
- The main API based on components that you can use to build your sheets, which is used to build the Folium Sheet itself and kept it for backwards compatibility with Vaul Drawer.
- The
wrapperAPI that provides a simpler way to create sheets with less code and complexity.
Note
The best part here is you can mix and match both APIs in the same project, or even in the same component, they're fully compatible with each other so you can moving from one to another without any problems and keep upgrading your codebase as you want.
What API should I use?
-
If you want keep backwards compatibility with Vaul Drawer, you should keep using the
main APIbased on components. -
If you're starting a new project or want a simpler way to create sheets, you should use the
wrapper API -
You care about performance and reducing bundle size because the
wrapper APIis tree-shakeable and only imports the components that you use in your project.
Differences between API.
When using the main API you have to specify more components to build your sheets, giving you a little more complexity.
You can take a look at the main differences below:
Overlay and Portal components
When using the main API you have to declare the <Drawer.Portal /> and <Drawer.Overlay /> components to render the drawer in a portal and provide the backdrop
which they're almost pretty the same on all sheets implementatins, because they don't take any props to modify their behavior.
"use client";
import { Drawer } from "folium";
export function MainAPISheet() {
return (
<Drawer.Root>
<Drawer.Trigger asChild>
<button className="button">
Open Drawer
</button>
</Drawer.Trigger>
<Drawer.Portal>
<Drawer.Overlay />
<Drawer.Content>
<Drawer.Title>Main API Sheet</Drawer.Title>
<Drawer.Description>
This is a sheet using the main API.
</Drawer.Description>
<Drawer.Close />
</Drawer.Content>
</Drawer.Portal>
</Drawer.Root>
);
}"use client";
import {
DrawerTrigger,
DrawerDescription,
DrawerContent,
DrawerRoot,
DrawerTitle,
} from "folium/wrapper";
export function WrapperAPISheet() {
return (
<DrawerRoot>
<DrawerTrigger>
<button className="button">
Open Drawer
</button>
</DrawerTrigger>
<DrawerContent >
<DrawerTitle className="font-extrabold text-4xl">Wrapper API Sheet</DrawerTitle>
<DrawerDescription className="font-semibold text-neutral-400">
This is a sheet using the wrapper API.
</DrawerDescription>
</DrawerContent>
</DrawerRoot>
);
}asChild props
When using the main API, elements that takes a child to render, needed to have the asChild prop to forward the ref and props to the child element.
In the wrapper API, all components that takes a child to render, already has the asChild prop set by default, so you don't need to specify it,
and if the child isn't a valid React element it will render a default element instead.
"use client";
import { Drawer } from "folium";
export function MainAPISheet() {
return (
<Drawer.Root>
<Drawer.Trigger asChild>
<button className="button">
Open Drawer
</button>
</Drawer.Trigger>
<Drawer.Portal>
<Drawer.Overlay />
<Drawer.Content>
<Drawer.Title asChild>
<h1 className="font-extrabold text-4xl">Main API Sheet</h1>
</Drawer.Title>
<Drawer.Description asChild>
<p className="font-semibold text-neutral-400">
This is a sheet using the main API.
</p>
</Drawer.Description>
<Drawer.Close />
</Drawer.Content>
</Drawer.Portal>
</Drawer.Root>
);
}"use client";
import {
DrawerTrigger,
DrawerDescription,
DrawerContent,
DrawerRoot,
DrawerTitle,
} from "folium/wrapper";
export function WrapperAPISheet() {
return (
<DrawerRoot>
<DrawerTrigger>
<button className="button">
Open Drawer
</button>
</DrawerTrigger>
<DrawerContent >
<DrawerTitle className="font-extrabold text-4xl">
<h1 className="font-extrabold text-4xl">Main API Sheet</h1>
</DrawerTitle>
<DrawerDescription >
<p className="font-semibold text-neutral-400">This is a sheet using the wrapper API.</p>
</DrawerDescription>
</DrawerContent>
</DrawerRoot>
);
}Nesting sheets
Both APis support nesting sheet, but the way to declare a little different between them. The main API provides comes with extra complexity and more params need it to be set to work properly.
The wrapper API allows you to skip two main things needed in the main API:
- You don't need to set the
directionprop again in the nested sheet, because it will inherit the direction from the parent sheet. - You don't need to change between
Drawer.RoottoDrawer.NestedRoot, theisNestedprop will take care of that for you.
"use client";
import { Drawer } from "folium";
export function NestedMainAPISheet(){
return (
<Drawer.Root direction="right">
<Drawer.Trigger asChild>
<button className="button">
Open Parent Sheet
</button>
</Drawer.Trigger>
<Drawer.Portal>
<Drawer.Overlay />
<Drawer.Content>
<Drawer.Title>Parent Sheet</Drawer.Title>
<Drawer.Description>
This is the parent sheet.
</Drawer.Description>
<Drawer.NestedRoot direction="right">
<Drawer.Trigger asChild>
<button className="button">
Open Nested Sheet
</button>
</Drawer.Trigger>
<Drawer.Portal>
<Drawer.Overlay />
<Drawer.Content>
<Drawer.Title>Nested Sheet</Drawer.Title>
<Drawer.Description>
This is the nested sheet.
</Drawer.Description>
</Drawer.Content>
</Drawer.Portal>
</Drawer.NestedRoot>
</Drawer.Content>
</Drawer.Portal>
)
}"use client";
import {
DrawerTrigger,
DrawerDescription,
DrawerContent,
DrawerRoot,
DrawerTitle,
} from "folium/wrapper";
export function NestedWrapperAPISheet(){
return (
<DrawerRoot direction="right">
<DrawerTrigger>
<button className="button">
Open Parent Sheet
</button>
</DrawerTrigger>
<DrawerContent>
<DrawerTitle>Parent Sheet</DrawerTitle>
<DrawerDescription>
This is the parent sheet.
</DrawerDescription>
<DrawerRoot isNested>
<DrawerTrigger>
<button className="button">
Open Nested Sheet
</button>
</DrawerTrigger>
<DrawerContent>
<DrawerTitle>Nested Sheet</DrawerTitle>
<DrawerDescription>
This is the nested sheet.
</DrawerDescription>
</DrawerContent>
</DrawerRoot>
</DrawerContent>
</DrawerRoot>
)
}