docs / api

API reference

The complete public surface for version 5.

Composition

Sheet.Root coordinates state and behavior while the remaining primitives describe the DOM. Use controlled values when another part of the application owns open or snap-point state.

`Sheet.Root`

Props controlling state and behavior for Sheet.Root.

interface SheetRootProps

Sheet.Root props
Prop	Signature	State	Default	Description
`children`	`ReactNode`	Required	—	The composed sheet primitives rendered within this root.
`open`	`boolean`	Optional	`false`	The controlled open state. Update it from onOpenChange when the sheet requests a change.
`defaultOpen`	`boolean`	Optional	`false`	The initial open state when open is uncontrolled.
`onOpenChange`	`(open: boolean, details: OpenChangeDetails) => void`	Optional	—	Called with the requested open state and the interaction that requested it.
`snapPoints`	`readonly SnapPoint[]`	Optional	`[{ id: 'content', value: 'content' }]`	The named height destinations available to the sheet.
`activeSnapPoint`	`string`	Optional	—	The controlled snap-point id. Update it from onSnapPointChange after a drag selects a destination.
`defaultSnapPoint`	`string`	Optional	`first snap-point id`	The initial snap-point id when activeSnapPoint is uncontrolled.
`onSnapPointChange`	`(id: string) => void`	Optional	—	Called with the destination id when a drag selects a snap point.
`modal`	`boolean`	Optional	`true`	Whether an open sheet contains focus and isolates the surrounding document.
`dismissible`	`boolean`	Optional	`true`	Whether Escape, a direct backdrop click, and a downward drag can request closing.

View Sheet.Root source

Run the controlled-state recipe.

Primitives

Each DOM primitive forwards its ref and native element props. Set asChild when an application-owned element should receive those props instead.

`Sheet`

Compound components for assembling a sheet while Root coordinates shared state and behavior.

Sheet

Sheet namespace members
Name	Signature	State	Default	Description
`Root`	`(props: SheetRootProps) => React.JSX.Element`	Required	—	Provides open state, snap-point state, layout, motion, and interactions to the composed primitives.
`Trigger`	`(props: SheetTriggerProps & React.RefAttributes<HTMLButtonElement>) => React.ReactNode`	Required	—	Renders a button that requests opening; preventing its click event cancels the request.
`Portal`	`(props: SheetPortalProps) => React.ReactPortal \| null`	Required	—	Mounts the present sheet subtree into document.body or a supplied container.
`Backdrop`	`(props: React.HTMLAttributes<HTMLDivElement> & { asChild?: boolean; } & React.RefAttributes<HTMLDivElement>) => React.ReactNode`	Required	—	Renders the backdrop and requests closing on an unprevented direct click when dismissal is enabled.
`Viewport`	`(props: React.HTMLAttributes<HTMLDivElement> & { asChild?: boolean; } & React.RefAttributes<HTMLDivElement>) => React.ReactNode`	Required	—	Renders and registers the element used to measure the sheet’s available space.
`Content`	`(props: React.HTMLAttributes<HTMLDivElement> & { asChild?: boolean; } & React.RefAttributes<HTMLDivElement>) => React.ReactNode`	Required	—	Renders the dialog surface, connects its accessible name and description, and handles focus and dragging.
`Handle`	`(props: React.HTMLAttributes<HTMLDivElement> & { asChild?: boolean; } & React.RefAttributes<HTMLDivElement>) => React.ReactNode`	Required	—	Renders the handle region; pointer gestures that start here are assigned to the sheet.
`Title`	`(props: React.HTMLAttributes<HTMLHeadingElement> & { asChild?: boolean; } & React.RefAttributes<HTMLHeadingElement>) => React.ReactNode`	Required	—	Renders a heading and registers its id as the dialog’s accessible name.
`Description`	`(props: React.HTMLAttributes<HTMLParagraphElement> & { asChild?: boolean; } & React.RefAttributes<HTMLParagraphElement>) => React.ReactNode`	Required	—	Renders a paragraph and registers its id as the dialog’s accessible description.
`Close`	`(props: React.ButtonHTMLAttributes<HTMLButtonElement> & { asChild?: boolean; } & React.RefAttributes<HTMLButtonElement>) => React.ReactNode`	Required	—	Renders a button that requests closing; preventing its click event cancels the request.

View Sheet source

`Sheet.Trigger`

Native button props for Sheet.Trigger, including support for a custom child element.

interface SheetTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement>

Sheet.Trigger props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Trigger source

`Sheet.Portal`

Props selecting the subtree and DOM target for Sheet.Portal.

interface SheetPortalProps

Sheet.Portal props
Prop	Signature	State	Default	Description
`children`	`ReactNode`	Required	—	The sheet subtree to render while the sheet is present.
`container`	`Element \| DocumentFragment \| null`	Optional	`document.body`	The element or document fragment that receives the portal; null also falls back to document.body.

View Sheet.Portal source

`Sheet.Backdrop`

Native div props for Sheet.Backdrop, including support for a custom child element.

HTMLAttributes<HTMLDivElement> & { asChild?: boolean; }

Sheet.Backdrop props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Backdrop source

`Sheet.Viewport`

Native div props for Sheet.Viewport, including support for a custom child element.

HTMLAttributes<HTMLDivElement> & { asChild?: boolean; }

Sheet.Viewport props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Viewport source

`Sheet.Content`

Native div props for Sheet.Content, including support for a custom child element.

HTMLAttributes<HTMLDivElement> & { asChild?: boolean; }

Sheet.Content props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Content source

`Sheet.Handle`

Native div props for Sheet.Handle, including support for a custom child element.

HTMLAttributes<HTMLDivElement> & { asChild?: boolean; }

Sheet.Handle props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Handle source

`Sheet.Title`

Native heading props for Sheet.Title, including support for a custom child element.

HTMLAttributes<HTMLHeadingElement> & { asChild?: boolean; }

Sheet.Title props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Title source

`Sheet.Description`

Native paragraph props for Sheet.Description, including support for a custom child element.

HTMLAttributes<HTMLParagraphElement> & { asChild?: boolean; }

Sheet.Description props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Description source

`Sheet.Close`

Native button props for Sheet.Close, including support for a custom child element.

ButtonHTMLAttributes<HTMLButtonElement> & { asChild?: boolean; }

Sheet.Close props
Prop	Signature	State	Default	Description
`asChild`	`boolean`	Optional	`false`	Merges the primitive props and forwarded ref into one child element instead of rendering the default element.

View Sheet.Close source

See the custom portal boundary.

Convenience API

BottomSheet assembles the standard portal, backdrop, viewport, content, handle, title, and optional description around the same root behavior.

`BottomSheet`

BottomSheet API
Name	Signature	State	Default	Description
`BottomSheet`	`(props: BottomSheetProps) => React.JSX.Element`	Exported	—	Convenience component that composes Root, Portal, Backdrop, Viewport, Content, Handle, Title, and optional Description.

View BottomSheet source

`BottomSheetProps`

Props for BottomSheet, combining the Root contract with the standard composed content.

interface BottomSheetProps extends Omit<SheetRootProps, 'children'>

BottomSheet props
Prop	Signature	State	Default	Description
`children`	`ReactNode`	Required	—	Content rendered after the generated handle, title, and optional description.
`title`	`ReactNode`	Required	—	Content rendered in Sheet.Title as the dialog name.
`description`	`ReactNode`	Optional	—	Optional content rendered in Sheet.Description as the dialog description.
`backdropProps`	`SheetBackdropProps`	Optional	—	Props forwarded to the composed Sheet.Backdrop.
`contentProps`	`SheetContentProps`	Optional	—	Props forwarded to the composed Sheet.Content.
`viewportProps`	`SheetViewportProps`	Optional	—	Props forwarded to the composed Sheet.Viewport.
`open`	`boolean`	Optional	`false`	The controlled open state. Update it from onOpenChange when the sheet requests a change.
`defaultOpen`	`boolean`	Optional	`false`	The initial open state when open is uncontrolled.
`onOpenChange`	`(open: boolean, details: OpenChangeDetails) => void`	Optional	—	Called with the requested open state and the interaction that requested it.
`snapPoints`	`readonly SnapPoint[]`	Optional	`[{ id: 'content', value: 'content' }]`	The named height destinations available to the sheet.
`activeSnapPoint`	`string`	Optional	—	The controlled snap-point id. Update it from onSnapPointChange after a drag selects a destination.
`defaultSnapPoint`	`string`	Optional	`first snap-point id`	The initial snap-point id when activeSnapPoint is uncontrolled.
`onSnapPointChange`	`(id: string) => void`	Optional	—	Called with the destination id when a drag selects a snap point.
`modal`	`boolean`	Optional	`true`	Whether an open sheet contains focus and isolates the surrounding document.
`dismissible`	`boolean`	Optional	`true`	Whether Escape, a direct backdrop click, and a downward drag can request closing.

View BottomSheetProps source

Public types

State callbacks report stable reasons, and snap points pair a stable identifier with a validated height value.

`OpenChangeDetails`

Details accompanying an onOpenChange request.

interface OpenChangeDetails

OpenChangeDetails API
Name	Signature	State	Default	Description
`reason`	`OpenChangeReason`	Required	—	The interaction that requested the open-state change.

View OpenChangeDetails source

`OpenChangeReason`

OpenChangeReason API
Name	Signature	State	Default	Description
`OpenChangeReason`	`'trigger' \| 'close' \| 'escape' \| 'backdrop' \| 'drag' \| 'imperative'`	Exported	—	Union of trigger, close, escape, backdrop, drag, and imperative change reasons.

Component interactions report trigger, close, escape, backdrop, or drag. Imperative is reserved by the public reason type.

View OpenChangeReason source

`SnapPoint`

A named sheet destination and the height it resolves to.

interface SnapPoint

SnapPoint API
Name	Signature	State	Default	Description
`id`	`string`	Required	—	A unique, stable identifier used by snap-point state and callbacks.
`value`	`SnapPointValue`	Required	—	The fraction, CSS length, or content height to resolve.

View SnapPoint source

`SnapPointValue`

SnapPointValue API
Name	Signature	State	Default	Description
`SnapPointValue`	number \| `${number}px` \| `${number}%` \| 'content'	Exported	—	A number from greater than zero through one for an available-height fraction, a positive px or percentage string, or content for measured content height.

Resolved heights are capped at the viewport space remaining after safe-area insets; invalid values are ignored.

View SnapPointValue source

Control named snap points in the runnable recipe.

Behavioral guarantees

Controlled open and activeSnapPoint values remain authoritative; update them from their callbacks.
onOpenChange identifies trigger, close, Escape, backdrop, or drag requests. Setting dismissible to false blocks passive dismissal while Sheet.Close remains available.
Modal content moves focus inside, contains focus, isolates the background, and restores the previously focused element when it closes.
Portal defaults to document.body and keeps content mounted until the closing motion finishes.
Transitions settle immediately when prefers-reduced-motion requests reduced motion.

Verify the motion contract with the reduced-motion recipe, or compare dismissal boundaries in the explicit-confirmation recipe.