Sheet · ui.voila.dev

Usage

import { Sheet } from "@voila.dev/ui/sheet";

<Sheet.Root>
	<Sheet.Trigger render={<Button variant="outline" />}>Details</Sheet.Trigger>
	<Sheet.Content side="right" size="lg">
		<Sheet.Header>
			<Sheet.Title>Project details</Sheet.Title>
			<Sheet.Description>Design sprint starting Saturday.</Sheet.Description>
		</Sheet.Header>
		<Sheet.Footer>
			<Button>Confirm booking</Button>
		</Sheet.Footer>
	</Sheet.Content>
</Sheet.Root>

A panel that slides in from an edge and keeps the page visible behind it. That is the difference from Dialog: a sheet is for working alongside what is on screen — a detail panel, a filter column — where a centred modal would say "stop everything". If the panel wants to be dragged and thrown like a native surface, that is Drawer. If it is a detail panel that will also be read on a phone, use ResponsiveSheet, which becomes a bottom drawer on small screens.

Recipes

Every edge

side picks the edge and size measures across it — so size is a width on left/right and a height on top/bottom. full covers the axis entirely, which is the honest choice on a narrow viewport when a partial panel would leave an unusable sliver.

API

Sheet.Root

Prop	Type	Default
`actionsRef`	`RefObject<DialogRootActions \| null>`	—	A ref to imperative actions.
`children`	`PayloadChildRenderFunction<unknown> \| ReactNode`	—	The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger.
`defaultOpen`	`boolean`	—	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
`defaultTriggerId`	`string \| null`	—	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
`disablePointerDismissal`	`boolean`	—	Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
`handle`	`DialogHandle<unknown>`	—	A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
`modal`	`"trap-focus" \| boolean`	—	Determines if the dialog enters a modal state when open. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
`onOpenChange`	`((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)`	—	Event handler called when the dialog is opened or closed.
`onOpenChangeComplete`	`((open: boolean) => void)`	—	Event handler called after any animations complete when the dialog is opened or closed.
`open`	`boolean`	—	Whether the dialog is currently open.
`triggerId`	`string \| null`	—	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).

Plus the DOM props of the element it renders. Source: sheet/components/sheet-root.tsx.

Sheet.Close

Prop	Type	Default
`className`	`string` \| `((state: DialogCloseState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`nativeButton`	`boolean`	—	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
`render`	`ComponentRenderFn<HTMLProps, DialogCloseState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogCloseState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-close.tsx.

Sheet.Content

Prop	Type	Default
`closeButtonLabel`	`string`	`"Close"`	Accessible name for that X. This package ships no translations.
`overlayClassName`	`string`	—	Classes for the backdrop behind the panel. `className` styles the panel itself.
`showCloseButton`	`boolean`	`true`	Draws the X in the corner.
`side`	`"bottom" \| "left" \| "right" \| "top"`	`"right"`	Edge the panel slides in from.
`size`	`SheetContentSize`	`"default"`	Thickness of the panel along the axis it slides on, `sm` through `full`.
`className`	`string` \| `((state: DialogPopupState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`finalFocus`	`boolean` \| `RefObject<HTMLElement \| null>` \| `((closeType: InteractionType) => void` \| `boolean` \| `HTMLElement` \| `null)`	—	Determines the element to focus when the dialog is closed.
`initialFocus`	`boolean` \| `RefObject<HTMLElement \| null>` \| `((openType: InteractionType) => void` \| `boolean` \| `HTMLElement` \| `null)`	—	Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.
`render`	`ComponentRenderFn<HTMLProps, DialogPopupState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogPopupState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-content.tsx.

Sheet.Description

Prop	Type	Default
`className`	`string` \| `((state: DialogDescriptionState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ComponentRenderFn<HTMLProps, DialogDescriptionState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogDescriptionState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-description.tsx.

Sheet.Footer

Prop	Type	Default
`render`	`ComponentRenderFn<HTMLProps, {}>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Plus every <div> prop. Source: sheet/components/sheet-footer.tsx.

Sheet.Header

Prop	Type	Default
`render`	`ComponentRenderFn<HTMLProps, {}>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Plus every <div> prop. Source: sheet/components/sheet-header.tsx.

Sheet.Overlay

Prop	Type	Default
`className`	`string` \| `((state: DialogBackdropState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`forceRender`	`boolean`	—	Whether the backdrop is forced to render even when nested.
`render`	`ComponentRenderFn<HTMLProps, DialogBackdropState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogBackdropState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-overlay.tsx.

Sheet.Portal

Prop	Type	Default
`className`	`string` \| `((state: DialogPortalState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`container`	`HTMLElement` \| `RefObject<HTMLElement \| ShadowRoot \| null>` \| `ShadowRoot` \| `null`	—	A parent element to render the portal element into.
`keepMounted`	`boolean`	—	Whether to keep the portal mounted in the DOM while the popup is hidden.
`render`	`ComponentRenderFn<HTMLProps, DialogPortalState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogPortalState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-portal.tsx.

Sheet.Title

Prop	Type	Default
`className`	`string` \| `((state: DialogTitleState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ComponentRenderFn<HTMLProps, DialogTitleState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogTitleState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-title.tsx.

Sheet.Trigger

Prop	Type	Default
`className`	`string` \| `((state: DialogTriggerState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`handle`	`DialogHandle<unknown>`	—	A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
`id`	`string`	—	ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop).
`nativeButton`	`boolean`	—	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
`payload`	`unknown`	—	A payload to pass to the dialog when it is opened.
`render`	`ComponentRenderFn<HTMLProps, DialogTriggerState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogTriggerState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: sheet/components/sheet-trigger.tsx.

ResponsiveSheet · Drawer · Dialog · Popover