Components
Sheet
A panel that slides up from the bottom, stops at sensible heights, and can be dragged or dismissed. The one-handed way to act without leaving the page.
Usage
pnpm dlx shadcn@latest add @opsinjs/sheet
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Sheet } from "@/components/ui/sheet"<Sheet open={open} onOpenChange={setOpen} title="Add a reading">
<Sheet.Content>
<Sheet.Description>What this sheet is for.</Sheet.Description>
{/* … */}
</Sheet.Content>
</Sheet>Examples
sheet · base base · style base-lyraOpen under the product themeA form the reader cannot leave by accident
dismissible={false} cancels the scrim, Escape and a downward drag, and
returns focus to the container.
sheet-a-form-that-stays-put · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Field } from "@/components/ui/field"
import { Sheet } from "@/components/ui/sheet"
export default function SheetAFormThatStaysPut() {
const [open, setOpen] = useState(false)
const [lastRoute, setLastRoute] = useState<string | null>(null)
return (
<div className="flex w-full flex-col items-center gap-opsin-4 p-opsin-4">
<p className="m-0 max-w-sm text-center text-opsin-footnote text-muted-foreground">
Open it, then try the escape key or a tap on the dimmed area. Neither
closes it. The close control in the header does.
</p>
<Button onClick={() => setOpen(true)}>Open the example form</Button>
{lastRoute ? (
<p className="m-0 text-opsin-caption1 text-muted-foreground">
Last route reported to the product: {lastRoute}
</p>
) : null}
<Sheet
open={open}
dismissible={false}
title="An example form"
onOpenChange={(nextOpen, route) => {
setLastRoute(route)
setOpen(nextOpen)
}}
footer={
<Button variant="primary" fullWidth onClick={() => setOpen(false)}>
Save the example
</Button>
}
>
<Sheet.Content>
<Field
label="Example note"
hint="Anything at all. Nothing here is stored."
>
<Field.Control name="example-note" autoComplete="off" />
</Field>
<p className="mt-opsin-4 mb-0 text-opsin-footnote text-muted-foreground">
The action stays below this text rather than after it, so a
software keyboard cannot cover it and scrolling cannot lose it.
</p>
</Sheet.Content>
</Sheet>
</div>
)
}Two detents, and the button the gesture owes
A second detents entry makes the grabber a real button, moving the sheet
between half and full with no pointer.
sheet-two-detents-and-a-control · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Sheet } from "@/components/ui/sheet"
const ROWS = Array.from({ length: 12 }, (unused, index) => ({
id: `row-${index + 1}`,
label: `Example item ${index + 1}`,
}))
export default function SheetTwoDetentsAndAControl() {
const [open, setOpen] = useState(false)
return (
<div className="flex w-full flex-col items-center gap-opsin-4 p-opsin-4">
<p className="m-0 max-w-sm text-center text-opsin-footnote text-muted-foreground">
The sheet opens at half the screen. The bar at the top is a button:
press it, or tab to it and press Enter, to move to the full screen and
back. Its name says which height the sheet is at, not which one the
press goes to.
</p>
<Button onClick={() => setOpen(true)}>Open the example list</Button>
<Sheet
open={open}
onOpenChange={(nextOpen) => setOpen(nextOpen)}
title="An example list"
detents={["half", "full"]}
footer={
<Button variant="quiet" fullWidth onClick={() => setOpen(false)}>
Leave the example list
</Button>
}
>
<Sheet.Content>
<ul className="m-0 flex list-none flex-col p-0">
{ROWS.map((row) => (
<li
key={row.id}
className="border-b border-border py-opsin-3 text-opsin-body last:border-b-0"
>
{row.label}
</li>
))}
</ul>
</Sheet.Content>
</Sheet>
</div>
)
}When to use it
Use it when
- A focused task started from the current screen, such as capturing a reading.
- Content reachable one-handed, where the thumb is.
- A surface whose height follows its content, not the viewport.
Do not use it when
- A repeated daily log entry, with its own contract and ceiling.Use
log-sheetinstead. - Asking permission to collect or share data.Use
consent-sheetinstead. - A decision the reader must make before continuing, at any width.Use
dialoginstead. - A panel that stays put while the reader works behind it.Use
surfaceinstead. - A small menu anchored to a control.Use
popoverinstead.
Accessibility
The rendered pass found no axe, target-size, focus-ring or reflow failure at 320px, and
nothing was changed. A modal sheet takes the dialog role, named by Sheet.Title, and
traps focus, with the page behind aria-hidden, not inert. Every gesture has a
control: close for drag-to-dismiss, grabber for drag-between-detents. The footer sits
outside the scrolling region and inside the keyboard inset, keeping the primary action
visible. Under prefers-reduced-motion the sheet crossfades in place, and the drag
still works. Close sinks when pressed, so a tap on the one guaranteed exit shows it
landed.
Residual items. Focus rings use a negative outline offset to stay visible inside the
clipped popup, meeting 2.4.7 and 1.4.11. No live region announces the new height. The
grabber's accessible name updates to name the next action instead. modal={false} pins
the sheet to the bottom while the page behind stays focusable, an unchecked obscured-focus
shape. Default and demo stay modal.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves through the sheet's own controls | Trapped in a modal sheet. |
| Shift+Tab | Moves backwards through the same controls | Reverse order; footer stays last. |
| Enter | Activates the focused control | Moves the grabber to the next detent. |
| Space | Activates the focused button, or scrolls the content | Scrolls Sheet.Content, not the page. |
| Escape | Closes a dismissible sheet and returns focus to what opened it | With dismissible={false}, returns to the container. |
| Arrow keys | Scroll the content, once focus is in the scrolling region | Only the grabber changes detent. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Sheet
Prop
Type
Generated from SheetProps in registry/bases/base/sheet.tsx.
detents defaults to ["content"]; its first entry is where the sheet opens.
half and full combine, content stands alone. onOpenChange receives the
close route second, so a product can ask before discarding unsaved work.
Sheet.Content
Prop
Type
Generated from SheetContentProps in registry/bases/base/sheet.tsx.
Sheet.Description
Prop
Type
Generated from SheetDescriptionProps in registry/bases/base/sheet.tsx.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On every rendered part | sheet-container, sheet-grabber, sheet-header, sheet-title, sheet-close, sheet-scrim, sheet-content, sheet-description, sheet-footer |
| data-open, data-closed, data-starting-style, data-ending-style | On the viewport, the scrim and the container | present |
| data-expanded | While the active detent is full | present |
| data-swiping, data-swipe-dismiss, data-swipe-direction | During a drag; dismiss means release would close it | present, direction down |
| data-drawer-content | Always; makes a touch there scroll, not swipe | present |