Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
sheet · base base · style base-lyraOpen under the product theme

A form the reader cannot leave by accident

dismissible={false} cancels the scrim, Escape and a downward drag, and returns focus to the container.

Theme
Density
Text
Status
Accent theme
Accent
sheet-a-form-that-stays-put · base base · style base-lyraOpen under the product theme
sheet-a-form-that-stays-put.tsx
"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.

Theme
Density
Text
Status
Accent theme
Accent
sheet-two-detents-and-a-control · base base · style base-lyraOpen under the product theme
sheet-two-detents-and-a-control.tsx
"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-sheet instead.
  • Asking permission to collect or share data.Use consent-sheet instead.
  • A decision the reader must make before continuing, at any width.Use dialog instead.
  • A panel that stays put while the reader works behind it.Use surface instead.
  • A small menu anchored to a control.Use popover instead.

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.

KeyActionNotes
TabMoves through the sheet's own controlsTrapped in a modal sheet.
Shift+TabMoves backwards through the same controlsReverse order; footer stays last.
EnterActivates the focused controlMoves the grabber to the next detent.
SpaceActivates the focused button, or scrolls the contentScrolls Sheet.Content, not the page.
EscapeCloses a dismissible sheet and returns focus to what opened itWith dismissible={false}, returns to the container.
Arrow keysScroll the content, once focus is in the scrolling regionOnly the grabber changes detent.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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

AttributeConditionValue
data-slotOn every rendered partsheet-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-styleOn the viewport, the scrim and the containerpresent
data-expandedWhile the active detent is fullpresent
data-swiping, data-swipe-dismiss, data-swipe-directionDuring a drag; dismiss means release would close itpresent, direction down
data-drawer-contentAlways; makes a touch there scroll, not swipepresent