# Sheet

A panel that slides in from an edge of the screen — left, right, or bottom.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/sheet
- Tier: Core and Pro

## Install

Sheet ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

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

- [Dialog](https://wunderui.com/components/dialog) for a short task or decision that needs full attention
- [Alert Dialog](https://wunderui.com/components/alert-dialog) for confirming an action that deletes data or removes access
- [Popover](https://wunderui.com/components/popover) for small content anchored to a control, without blocking the page

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | 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. |
| `Enter` or `Space` | 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 `disablePointerDismissal` is set. |

## Behavior

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

- `Sheet`: Holds the open state and links the trigger to the panel, either controlled or uncontrolled. It renders nothing itself.
- `SheetTrigger`: The element that opens the sheet, usually a button. Focus returns to it when the sheet closes.
- `SheetContent`: 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.
- `Close button`: The icon button in the top right corner, named Close for screen readers. Turn it off only when the content offers another way out.
- `SheetHeader`: Stacks the title and the description at the top of the panel.
- `SheetTitle`: Names the sheet. Screen readers announce it when the sheet opens, so keep it even when the design shows none.
- `SheetDescription`: One or two sentences on what the sheet is for, read out after the title.
- `Your content`: 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.
- `SheetClose`: Closes the sheet. Pass it a Cancel or Done button.
- `Expand`
- `Resize Handle`
- `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.
- Always include a SheetTitle, even when the design shows none. It is the only name the sheet has for screen readers.
- Choose the bottom side for phones and the right for desktop detail views. The bottom sheet is capped at 80 % of the screen height.
- 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.
- 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 hide the close button without another way out. Add a SheetClose button, since Escape is the only other route for keyboard users.
- Don't stack a sheet on a sheet. Replace the content of the open one, or send people to a page.

## API reference

### Sheet

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<DialogRoot.Actions \| null> |  | A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called. |
| children | React.ReactNode \| PayloadChildRenderFunction<Payload> |  | 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 | false | 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 | false | 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<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. |
| modal | boolean \| 'trap-focus' | true | Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user… |
| onOpenChange | ((open: boolean, eventDetails: DialogRoot.ChangeEventDetails) => 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… |

### SheetClose

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| nativeButton | boolean | true | 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 | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

### SheetContent

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| container | SheetContainer |  | Portal into this element instead of the body, e.g. a device frame. The element needs its own containing block (a `transform`) so the sheet and its scrim cover the frame, not the viewport. |
| defaultExpanded | boolean | false | Whether the sheet opens expanded (uncontrolled). Default false. |
| defaultWidth | number |  | The width in px the sheet opens with when it is resizable. Default 384 (24rem), or the stored width. |
| expandable | boolean | false | An Expand button in the header, beside Close, that switches the sheet to the full width of the screen and back. Side sheets only (`left`, `right`); left out where the sheet already takes the full width (a phone). |
| expanded | boolean |  | Whether the sheet fills the screen (controlled). |
| finalFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void) |  | Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`… |
| initialFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| HTMLElement \| null \| void) |  | 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… |
| maxWidth | number | SHEET_MAX_WIDTH | Widest width in px the handle allows. Default 960; the sheet never grows past the screen. |
| minWidth | number | SHEET_MIN_WIDTH | Narrowest width in px the handle allows. Default 320. |
| onExpandedChange | (expanded: boolean) => void |  |  |
| onWidthChange | (width: number) => void |  | Called with the new width in px whenever the handle changes it. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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. |
| resizable | boolean | false | A 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`, `right`); left out where the sheet already takes the full width (a p… |
| showCloseButton | boolean | true | Shows 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 `SheetClose`. |
| side | "right" \| "left" \| "bottom" | "right" | The edge the panel comes from: `right` (default), `left` or `bottom`. Side sheets are at most 384 px wide; the bottom sheet is capped at 80 % of the screen height. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| theme | "inherit" \| "dark" | "inherit" | `inherit` (default) follows the page; `dark` renders the sheet in the dark theme (a `.dark` scope on the content), e.g. a drawer opened from a dark or coloured bar on a light page. |
| widthStorageKey | string |  | Remembers the width in localStorage under this key, so the sheet opens as wide as it was left. |

Also accepts React.HTMLAttributes attributes.

### SheetDescription

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### SheetHeader

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### SheetTitle

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### SheetTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| handle | DialogHandle<Payload> |  | 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 | true | 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 | Payload |  | A payload to pass to the dialog when it is opened. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Width: narrow, default and wide

### Content: form, details, filters and long content

### Close: the corner button, or only the footer

### Content state: loaded, loading and error

### Size: drag the width or expand to the full screen

### Theme: dark on a light page, or the page's theme

## In context

### Edit profile: a form that validates and saves

An empty name is flagged on the field and the sheet stays open. While the request runs, the primary action shows its pending state and Cancel is disabled; the sheet closes when done.

### Filters: a bottom sheet on a phone

The list behind the sheet follows each choice, and the primary action says how many results the filters give. The bottom sheet is capped at 80 % of the screen height.

### Member details: opened from a row of a list

Choosing a row opens the sheet with that person. Focus returns to the same row when the sheet closes.

## For AI agents

`get_component("sheet")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
