Skip to main content

Sheet

A container that overlays the current view from the edge of the screen.

When to use

  • Show side-panel content that slides in from the left or right edge, such as a filter panel, a detail or inspector view, a navigation drawer, or a mobile menu.
  • Let the user complete a task without losing the context of the view beneath the sheet.
  • Prefer Dialog for a centered modal.
  • Prefer AlertDialog for a destructive or irreversible confirmation.
  • Prefer Sidebar for the persistent navigation of the app.

Layering and z-index

Sheet.Content renders its floating layer at Tailwind z-60, Mantle's overlay tier, above every float (z-50). Floats composed inside the content portal into the positioner (data-slot="sheet-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.

Sheet, Dialog, and AlertDialog each render their own backdrop, so stacking modal layers compounds the dim and blur effect on the layers underneath.

UI above an open sheet

UI that must take clicks above an open sheet, such as a consent banner, carries the overlay-prompt class. A click inside it does not count as an outside click. Add pointer-events-auto too, because the open sheet sets pointer-events: none on <body>. mantle's Toaster does both.

<div className="overlay-prompt pointer-events-auto fixed inset-x-0 bottom-0 z-max">	<ConsentBanner /></div>

The class reaches pointer input only. The open sheet traps keyboard focus and hides outside content from assistive technology with aria-hidden, so a keyboard or screen reader user cannot reach the banner. Put a control that every user must reach inside the sheet content.

Third-party popups

A script can show its own popup in a frame on <body>, above the sheet. A payment script does this for a 3-D Secure challenge and for a wallet sign-in. While that frame is on top at the center of the viewport, the sheet yields to the popup:

  • Focus that the script moves into the popup stays there. The focus trap does not take it back.
  • Escape does not close the sheet. It moves focus into the popup, and the popup then takes the keyboard.
  • A click in the popup is not an outside click.

The sheet finds the popup with a hit test at the center of the viewport. The popup counts when:

  • the element on top there is a frame, and the frame takes pointer input
  • the frame is in a child of <body> that has a position and a z-index at or above the z-60 of the sheet

An open sheet sets pointer-events: none on <body>, so a frame must set pointer-events: auto to take a click. Stripe's popups set it. If the popup of another script does not, set it on the frame in your CSS.

A popup that shows page elements at the center of the viewport does not count, also when it holds a frame at another place. If the script can render its popup into an element that you choose, give it an element in the sheet.

An open sheet hides the rest of the page from assistive technology. That includes a popup that was on the page before the sheet opened. The sheet removes that aria-hidden from the popup when the page gets a focus event for the move into the popup. Firefox sends no such event when focus was in another frame or on <body>.

Your code still does two things:

  • Close the sheet only after the popup closes. A payment script saves the <body> style and the aria-hidden state of the page when its popup opens. It puts them back when the popup closes. If the sheet closes in between, the page takes no clicks and a screen reader finds no content.
  • Move focus when the script gives you the result. The browser does not return focus to the sheet when the popup closes.

The example runs confirmWithBank, a stand-in for a payment script. It does what Stripe.js does to the page:

  • It puts a wrapper on <body> that fills the viewport above every layer.
  • It shows the bank's page in a frame with its own origin.
  • It calls focus() on the frame from the page.
  • It saves the <body> style, and puts that style back when the popup closes.

Select Save card. In the bank's frame, select the code field and type a code. Press Escape in the frame to cancel the check: the popup closes, the sheet stays open, and focus moves to the result. While the popup is open, the sheet ignores each close request.

Examples

Router or state management controlled Sheet

Control when to render a Sheet with a router or with outside state management to open and close it programmatically without a Sheet.Trigger.

Setting a preferred width of the Sheet

By default, a Sheet's content width is responsive with a default preferred width: the maximum width of the Sheet.Content when the window viewport is larger than the mobile breakpoint (sm). Control the preferred width of the Sheet.Content with the preferredWidth prop:

With TanStack Form

Sheets often host small create/edit forms. Use TanStack Form with Field for label, description, and error wiring. Sheet.Content is a flex column, so wrap Sheet.Body and Sheet.Footer in a display: contents form; the footer's submit button participates in the form while the body keeps its scrollable layout. Close the sheet from the form's onSubmit (it only runs once validation passes) and reset the form when the sheet closes so a cancelled draft doesn't leak into the next open.

Composition

Compose the parts of a Sheet together to build your own:

Sheet.Root├── Sheet.Trigger└── Sheet.Content    ├── Sheet.Header    │   ├── Sheet.TitleGroup    │   │   ├── Sheet.Title    │   │   └── Sheet.Actions    │   └── Sheet.Description    ├── Sheet.Body    └── Sheet.Footer        └── Sheet.Close

Polymorphism

Sheet.Trigger, Sheet.Close, Sheet.Content, Sheet.Title, Sheet.Description, and Sheet.CloseIconButton accept asChild, which renders your single child instead of the part's default element while keeping its styling and behavior.

Sheet.Trigger asChild is the most common: it makes your own Button open the sheet rather than nesting a button inside one. Sheet.Close asChild lets any element dismiss the sheet, which is handy for a "Cancel" button in Sheet.Footer, and Sheet.Title asChild adjusts the heading level to fit the page outline.

Sheet.Root renders no DOM of its own, so it takes no asChild. Sheet.Header, Sheet.Body, Sheet.Footer, Sheet.TitleGroup, and Sheet.Actions are layout containers that do not currently accept it.

API Reference

The Sheet components are built on top of Radix Dialog.

Sheet.Root

The root component for a Sheet. Should compose the Sheet.Trigger and Sheet.Content. Acts as a stateful provider for the Sheet's open/closed state.

Every Sheet part reads a dialog scope of its own, so it binds to the nearest Sheet.Root and never to a Dialog.Root. The reverse holds too: a Dialog.Trigger or Command.SearchTrigger inside Sheet.Content reaches the Dialog.Root or Command.DialogRoot above the sheet, not the sheet. A Dialog.Close inside a sheet with no Dialog.Root above it throws Radix's "must be used within Dialog"; use Sheet.Close to close a sheet.

Sheet renders its floating layer at Tailwind z-60, Mantle's overlay tier, above every float (z-50). Floats composed inside the content portal into the positioner (data-slot="sheet-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.

All props from Radix Dialog.Root.

Sheet.Trigger

The button trigger for a Sheet. Should be rendered as a child of the Sheet component. Renders an unstyled button by default, but can be customized with the asChild prop.

Opens the nearest Sheet.Root. It never opens a Dialog.Root, and a Dialog.Trigger inside the sheet never opens the sheet.

All props from Radix Dialog.Trigger.

Sheet.Close

The close button for a Sheet. Should be rendered as a child of the Sheet.Content component. Usually contained within the Sheet.Footer component. Renders an unstyled button by default, but can be customized with the asChild prop.

Closes the nearest Sheet.Root. It never closes a Dialog.Root, and a Dialog.Close inside the sheet never closes the sheet.

Radix Dialog.Close props.

Sheet.Content

The main container for a Sheet. Should be rendered as a child of the Sheet component. Renders on top of the overlay backdrop. Should contain the Sheet.Header, Sheet.Body, and Sheet.Footer.

Sheet.Content renders its floating layer at Tailwind z-60, Mantle's overlay tier, above every float (z-50). Floats composed inside the content portal into the positioner (data-slot="sheet-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.

Sheet.Content renders inside a positioner element (data-slot="sheet-positioner") that lays out the content and receives floats portaled from inside the sheet. The full stacking contract lives at Stacking Layers.

All props from Radix Dialog.Content, plus:

PropTypeDefaultDescription
preferredWidth?`sm:max-w-${string}`"sm:max-w-120"The preferred width of the Sheet.Content as a tailwind max-w- class. By default, a Sheet's content width is responsive with a default preferred width: the maximum width of the Sheet.Content when the window viewport is larger than the mobile breakpoint (sm).
side?"left" | "right""right"The side of the screen the sheet slides in from.

Sheet.CloseIconButton

An icon button that closes the Sheet when clicked. Should be rendered within the Sheet.Header as a child of Sheet.Actions.

PropTypeDefaultDescription
appearance?"filled" | "ghost" | "outlined""ghost"The visual style of the close icon button.
intent?"neutral""neutral"The tone of the close icon button. IconButton draws the neutral tone only.
size?"xs" | "sm" | "md" | "lg" | "xl""md"The size of the close icon button.
label?string"Close Sheet"The accessible label for the close button. Important for screen readers.

All remaining props (except icon, which is fixed to an X icon) forward to the Mantle IconButton.

Sheet.Body

The body container for a Sheet. This is where you would typically place the main content of the sheet, such as forms or text. Should be rendered as a child of Sheet.Content.

All props from div.

Sheet.Header

The header container for a Sheet. This is where you would typically place the title, description, and actions. Should be rendered as a child of Sheet.Content.

All props from div.

Sheet.Footer

The footer container for a Sheet. This is where you would typically place close and submit buttons. Should be rendered as a child of Sheet.Content.

All props from div.

Sheet.Title

The title for a Sheet. Typically rendered as a child of Sheet.TitleGroup. Defaults to an h2 element, but can be changed via the asChild prop.

All props from Radix Dialog.Title.

Sheet.TitleGroup

A group container for the title and actions of a Sheet. Typically rendered as a child of Sheet.Header.

All props from div.

Sheet.Description

A description for a Sheet. Typically rendered as a child of Sheet.Header.

All props from Radix Dialog.Description.

Sheet.Actions

A group container for the actions of a Sheet. Typically rendered as a child of Sheet.TitleGroup.

All props from div.