Skip to content
WunderUI

Sheet

Pro

A panel that slides in from the edge of the screen for a detail view, an edit form or filters, while the page stays visible behind it.

Playground

Escape, the close button or a click on the backdrop closes it.

Installation

Sheet comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetContentProps,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@wunderui/react"

Then use it:

tsx
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet"
import { Button } from "@/components/ui/button"

export function EditProfile() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="plain" />}>Edit profile</SheetTrigger>
      <SheetContent>
        <SheetHeader>
          <SheetTitle>Edit profile</SheetTitle>
          <SheetDescription>Update your account details.</SheetDescription>
        </SheetHeader>
      </SheetContent>
    </Sheet>
  )
}

Expected result: You see an Edit profile button that opens a panel from the right with a title, a description and a close button. The close button or Escape closes it.

When to use

Use Sheet for

  • A detail view of a row, such as a member, an invoice or a task, that keeps the list visible
  • An edit form or a settings panel that is longer than a dialog should be
  • Filters and sorting on a phone, as a bottom sheet

Use something else for

  • Dialog for a short task or decision that needs full attention
  • Alert Dialog for confirming an action that deletes data or removes access
  • Popover for small content anchored to a control, without blocking the page

Width

The sheet is as wide as its content, up to 384 px, and fills the screen on a phone. A class on SheetContent changes the width.

Theme

theme="dark" opens the sheet in the dark theme on a light page, e.g. a drawer from a dark or coloured bar (Navbar passes it on as drawerTheme). Left out, the sheet follows the page.

Members

Content

The panel is a column: header with title and description, then your content, then the actions. A long body scrolls while the header and actions stay in place.

Resize and expand

Set resizable and the inner edge gets a handle: drag it, or focus it and use the arrow keys (16 px, Shift 64 px, Home and End for the limits). The width stays between 320 and 960 px by default and never goes past the screen, and a storage key remembers it. Set expandable and an Expand button beside Close switches the sheet to the full width and back. Both work on side sheets only, and both are left out where the sheet already takes the full width (a phone).

Size

Members

Close

The corner close button is on by default. Without it, the footer must offer a way out, such as a Cancel or Close button wrapped in SheetClose.

Content state

What the panel shows while its content loads and when it cannot be loaded. The title and the way out are there in every state.

Keyboard interactions

The buttons and fields are native, so the browser handles focus and activation. While a modal sheet is open the page behind it is inert.

TaborShiftTab
Moves focus between the close button, the fields and the buttons. In a modal sheet focus stays inside, wrapping from the last element to the first.
EnterorSpace
Presses the focused button. In a text field, Enter submits only when the field sits in a form.
Escape
Closes the sheet. A click on the backdrop closes it too, unless is set.

Behavior and motion

What the sheet does with focus, state, content and motion.

Modal
By default the page behind an open sheet is inert and does not scroll, and the panel is a dialog named by its title and described by its description. Other modes only trap focus or drop the trap too.
Focus
When the sheet opens, focus moves to the first focusable element, or one you choose. When it closes, focus returns to the trigger, or somewhere you set.
Closing
The close button, a SheetClose button, Escape and a click on the backdrop all close it. You can ignore the backdrop, for example while a request runs.
Side
Side sheets fill the screen height and are as wide as their content, up to 384 px (full width on narrower screens). Bottom spans the width, caps at 80 % of the height with 16 px top corners.
Scrolling
The panel is a flex column. Give a long body a scrolling region so it scrolls between the header and the actions, and make that region focusable with a label so keyboard users can scroll it.
Other container
The container option portals the panel and backdrop into another element, such as a device frame. That element needs its own containing block, for example a transform, so the sheet covers the frame.
Previews in these docs
The real panel is portalled to the end of the document and fixed to the screen. The previews here draw the same panel inside the card, with the same behaviour, so it does not cover the page.
Opening and closing
The panel slides in from its edge with a short blur and the backdrop fades, and closing is a step faster. Only transform, opacity and the blur change.
Reduced motion
With reduced motion the slide and blur are switched off, and the panel only fades in and out.

Anatomy

The figure marks a side sheet with a form. The Sheet root and the trigger sit on the page behind it and draw nothing themselves.

Edit profile

Update your account details.

  • data-slot="sheet"

    Holds the open state and links the trigger to the panel, either controlled or uncontrolled. It renders nothing itself.

  • data-slot="sheet-trigger"Optional

    The element that opens the sheet, usually a button. Focus returns to it when the sheet closes.

  • data-slot="sheet-content"

    The panel. It brings its own portal and backdrop, slides in from the right by default, keeps focus inside while open and shows a close button.

  • Optional

    The icon button in the top right corner, named Close for screen readers. Turn it off only when the content offers another way out.

  • Optional

    Stacks the title and the description at the top of the panel.

  • data-slot="sheet-title"

    Names the sheet. Screen readers announce it when the sheet opens, so keep it even when the design shows none.

  • data-slot="sheet-description"Optional

    One or two sentences on what the sheet is for, read out after the title.

  • Optional

    Fields, details or a list. The panel is a column with a 16 px gap, and a scrolling body keeps the header and actions in place.

  • data-slot="sheet-close"Optional

    Closes the sheet. Pass it a Cancel or Done button.

  • data-slot="sheet-expand"Optional
  • data-slot="sheet-resize-handle"
  • data-slot="sheet-fit"

Best practices

  • Do

    Use it for a detail view, an edit form or filters that need more room than a dialog and should keep the page visible behind them.

  • Do

    Always include a SheetTitle, even when the design shows none. It is the only name the sheet has for screen readers.

  • Do

    Choose the bottom side for phones and the right for desktop detail views. The bottom sheet is capped at 80 % of the screen height.

  • Do

    Put the primary action and a Cancel button at the bottom of the content, with Cancel wrapped in SheetClose. The corner button alone is easy to miss on a form.

  • Do

    Keep what people typed when the sheet closes by mistake, or ask before you throw it away.

  • Don’t

    Don't use a Sheet for a short decision. A Dialog keeps people in the flow, and an Alert Dialog confirms an action that deletes data.

  • Don’t

    Don't hide the close button without another way out. Add a SheetClose button, since Escape is the only other route for keyboard users.

  • Don’t

    Don't stack a sheet on a sheet. Replace the content of the open one, or send people to a page.

API reference

Sheet wraps the Base UI dialog and passes its props on, and its parts take className, style and render. The root takes the open state, and SheetHeader is a plain div.

Holds the open state and links the trigger to the panel, either controlled or uncontrolled. It renders nothing itself.

PropTypeDefaultDescription
openboolean—Whether the dialog is currently open.
defaultOpenbooleanfalseWhether the dialog is initially open. To render a controlled dialog, use the prop instead.
onOpenChange(open, eventDetails) => void—Event handler called when the dialog is opened or closed.
modalboolean | "trap-focus"trueDetermines if the dialog enters a modal state when open. - : user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - : user…
disablePointerDismissalbooleanfalseWhether 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.
actionsRefRefObject<DialogRoot.Actions | null>—A ref to imperative actions. - : Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - : Closes the dialog imperatively when called.
childrenReactNode | PayloadChildRenderFunction<Payload>—The content of the dialog. This can be a regular React node or a render function that receives the of the active trigger.
defaultTriggerIdstring | null—ID of the trigger that the dialog is associated with. This is useful in conjunction with the prop to create an initially open dialog.
handleDialogHandle<Payload>—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.
onOpenChangeComplete(open) => void—Event handler called after any animations complete when the dialog is opened or closed.
triggerIdstring | null—ID of the trigger that the dialog is associated with. This is useful in conjunction with the prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the prop is…

The element that opens the sheet, usually a button. Focus returns to it when the sheet closes.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
handleDialogHandle<Payload>—A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
idstring—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 prop).
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
payloadPayload—A payload to pass to the dialog when it is opened.

The panel. It brings its own portal and backdrop, slides in from the right by default, keeps focus inside while open and shows a close button.

PropTypeDefaultDescription
side"right" | "left" | "bottom""right"The edge the panel comes from: (default), or . Side sheets are at most 384 px wide; the bottom sheet is capped at 80 % of the screen height.
showCloseButtonbooleantrueShows the close button in the top right corner. Turn it off only when the content offers another way out, such as a Cancel button in .
initialFocusboolean | RefObject<HTMLElement | null> | (openType) => unknown—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 ke…
finalFocusboolean | RefObject<HTMLElement | null> | (closeType) => unknown—Determines the element to focus when the dialog is closed. - : Do not move focus. - : Move focus based on the default behavior (trigger or previously focused element). - : Move focus to the ref element. - …
containerSheetContainer—Portal into this element instead of the body, e.g. a device frame. The element needs its own containing block (a ) so the sheet and its scrim cover the frame, not the viewport.
classNamestring | (state) => string | undefined—CSS class applied to the element, or a function that returns a class based on the component's state.
defaultExpandedbooleanfalseWhether the sheet opens expanded (uncontrolled). Default false.
defaultWidthnumber—The width in px the sheet opens with when it is resizable. Default 384 (24rem), or the stored width.
expandablebooleanfalseAn Expand button in the header, beside Close, that switches the sheet to the full width of the screen and back. Side sheets only (, ); left out where the sheet already takes the full width (a phone).
expandedboolean—Whether the sheet fills the screen (controlled).
maxWidthnumberSHEET_MAX_WIDTHWidest width in px the handle allows. Default 960; the sheet never grows past the screen.
minWidthnumberSHEET_MIN_WIDTHNarrowest width in px the handle allows. Default 320.
onExpandedChange(expanded) => void—
onWidthChange(width) => void—Called with the new width in px whenever the handle changes it.
resizablebooleanfalseA handle on the inner edge to drag the width, or focus it and use the arrow keys (16 px, Shift 64 px, Home and End for the minimum and maximum). Side sheets only (, ); left out where the sheet already takes the full width (a p…
theme"inherit" | "dark""inherit" (default) follows the page; renders the sheet in the dark theme (a scope on the content), e.g. a drawer opened from a dark or coloured bar on a light page.
widthStorageKeystring—Remembers the width in localStorage under this key, so the sheet opens as wide as it was left.

Stacks the title and the description at the top of the panel.

Names the sheet. Screen readers announce it when the sheet opens, so keep it even when the design shows none.

One or two sentences on what the sheet is for, read out after the title.

Closes the sheet. Pass it a Cancel or Done button.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("sheet")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.