# Sheet

A dialog that slides in from an edge of the screen and holds content related to the page.

```tsx
import { Button } from "@/components/ui/button"
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet"
import { VStack } from "@/components/ui/stack"

export default function SheetDemo() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>Open</SheetTrigger>
      <SheetContent>
        <SheetHeader>
          <SheetTitle>Profile</SheetTitle>
          <SheetDescription>Update your name and username, then save.</SheetDescription>
        </SheetHeader>
        <VStack grow paddingInline={4}>
          <FieldGroup gap={6}>
            <Field>
              <FieldLabel>Name</FieldLabel>
              <Input id="sheet-demo-name" defaultValue="Ada Lovelace" />
            </Field>
            <Field>
              <FieldLabel>Username</FieldLabel>
              <Input id="sheet-demo-username" defaultValue="@lovelace" />
            </Field>
          </FieldGroup>
        </VStack>
        <SheetFooter>
          <Button type="submit">Save changes</Button>
          <SheetClose render={<Button variant="outline" />}>Close</SheetClose>
        </SheetFooter>
      </SheetContent>
    </Sheet>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/sheet
```

Needs the [arene setup](https://www.arene.style/docs/installation) first. Also adds [Button](https://www.arene.style/docs/components/button).

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx @phosphor-icons/react
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation), and copy `state-styles.ts` from the same page.
   Copy `states.ts` for the shared popup surface and install the
   [Button](https://www.arene.style/docs/components/button) for the close control.

3. Paste this source into the file named in its title.

   ```tsx title="components/ui/sheet.tsx"
   "use client"

   import type { CSSProperties } from "react"
   import { useRender } from "@base-ui/react/use-render"
   import { Dialog as SheetPrimitive } from "@base-ui/react/dialog"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"
   import { XIcon } from "@phosphor-icons/react/dist/csr/X"

   import { Button } from "@/components/ui/button"
   import { stateStyles } from "@/lib/state-styles"
   import { breakpoints } from "@/theme/breakpoints.stylex"
   import { states } from "@/theme/states"
   import { color, duration, ease, layer, leading, shadow, space, text } from "@/theme/tokens.stylex"

   const styles = stylex.create({
     hidden: { transform: "var(--arene-sheet-closed-transform)" },
     ending: {
       transitionDuration: {
         default: duration.panel,
         "@media (prefers-reduced-motion: reduce)": "0s",
       },
     },
     overlay: {
       position: "fixed",
       inset: 0,
       zIndex: layer.popup,
       backgroundColor: color.overlay,
       backdropFilter: "blur(2px)",
       transitionProperty: "opacity",
       transitionDuration: {
         default: duration.sheet,
         "@media (prefers-reduced-motion: reduce)": "0s",
       },
       transitionTimingFunction: ease.decelerate,
     },
     content: {
       position: "fixed",
       zIndex: layer.popup,
       display: "flex",
       flexDirection: "column",
       gap: space.s4,
       boxShadow: shadow.popupLifted,
       fontSize: text.sm,
       lineHeight: leading.sm,
       transitionProperty: "transform",
       transitionDuration: {
         default: duration.sheet,
         "@media (prefers-reduced-motion: reduce)": "0s",
       },
       transitionTimingFunction: ease.decelerate,
     },
     close: { position: "absolute", top: space.s2_5, right: space.s2_5 },
     header: { display: "grid", rowGap: space.s1, padding: space.s4 },
     footer: {
       display: "flex",
       flexDirection: "column",
       gap: space.s2,
       marginBlockStart: "auto",
     },
     title: { fontSize: text.base, lineHeight: leading.base, fontWeight: 500 },
     description: { color: color.mutedForeground },
   })

   const sides = stylex.create({
     top: {
       top: 0,
       insetInline: 0,
       height: "auto",
       "--arene-sheet-closed-transform": "translate3d(0, calc(-100% - 2px), 0)",
     },
     right: {
       right: 0,
       insetBlock: 0,
       height: "100%",
       width: { default: "75%", [breakpoints.md]: "24rem" },
       "--arene-sheet-closed-transform": "translate3d(calc(100% + 2px), 0, 0)",
     },
     bottom: {
       bottom: 0,
       insetInline: 0,
       height: "auto",
       "--arene-sheet-closed-transform": "translate3d(0, calc(100% + 2px), 0)",
     },
     left: {
       left: 0,
       insetBlock: 0,
       height: "100%",
       width: { default: "75%", [breakpoints.md]: "24rem" },
       "--arene-sheet-closed-transform": "translate3d(calc(-100% - 2px), 0, 0)",
     },
   })

   const sheetStyles = { content: [states.popupSurface, styles.content], sides }

   type SheetSide = keyof typeof sides

   type Overrides = { xstyle?: StyleXStyles; className?: string }
   type StateOverrides = Overrides & { style?: CSSProperties }

   function Sheet<Payload>(props: SheetPrimitive.Root.Props<Payload>) {
     return <SheetPrimitive.Root {...props} />
   }

   function SheetTrigger(props: SheetPrimitive.Trigger.Props) {
     return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
   }

   function SheetPortal(props: SheetPrimitive.Portal.Props) {
     return <SheetPrimitive.Portal {...props} />
   }

   function SheetClose(props: SheetPrimitive.Close.Props) {
     return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
   }

   type SheetOverlayProps = Omit<SheetPrimitive.Backdrop.Props, "className" | "style"> & StateOverrides

   function SheetOverlay({ xstyle, className, style, ...props }: SheetOverlayProps) {
     return (
       <SheetPrimitive.Backdrop
         data-slot="sheet-overlay"
         {...props}
         {...stateStyles(
           (state) => [
             styles.overlay,
             (state.transitionStatus === "starting" || state.transitionStatus === "ending") &&
               states.transparent,
             state.transitionStatus === "ending" && styles.ending,
             xstyle,
           ],
           { className, style },
         )}
       />
     )
   }

   type SheetContentProps = Omit<SheetPrimitive.Popup.Props, "className" | "style"> &
     StateOverrides & {
       side?: SheetSide
       showCloseButton?: boolean
       overlayProps?: SheetOverlayProps
     }

   function SheetContent({
     xstyle,
     className,
     style,
     children,
     side = "right",
     showCloseButton = true,
     overlayProps,
     ...props
   }: SheetContentProps) {
     return (
       <SheetPortal>
         <SheetOverlay {...overlayProps} />
         <SheetPrimitive.Popup
           data-slot="sheet-content"
           data-side={side}
           {...props}
           {...stateStyles(
             (state) => [
               states.popupSurface,
               styles.content,
               sides[side] ?? sides.right,
               (state.transitionStatus === "starting" || state.transitionStatus === "ending") &&
                 styles.hidden,
               state.transitionStatus === "ending" && styles.ending,
               xstyle,
             ],
             { className, style },
           )}
         >
           {children}
           {showCloseButton && (
             <SheetClose
               render={<Button variant="ghost" size="icon-sm" xstyle={styles.close} />}
               aria-label="Close"
             >
               <XIcon aria-hidden="true" />
             </SheetClose>
           )}
         </SheetPrimitive.Popup>
       </SheetPortal>
     )
   }

   function SheetHeader({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & Overrides) {
     const sx = stylex.props(styles.header, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "sheet-header",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function SheetFooter({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & Overrides) {
     const sx = stylex.props(states.trayFooter, styles.footer, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "sheet-footer",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function SheetTitle({ xstyle, className, ...props }: SheetPrimitive.Title.Props & Overrides) {
     const sx = stylex.props(styles.title, xstyle)
     return (
       <SheetPrimitive.Title
         data-slot="sheet-title"
         {...sx}
         {...props}
         className={clsx(sx.className, className)}
       />
     )
   }

   function SheetDescription({
     xstyle,
     className,
     ...props
   }: SheetPrimitive.Description.Props & Overrides) {
     const sx = stylex.props(styles.description, xstyle)
     return (
       <SheetPrimitive.Description
         data-slot="sheet-description"
         {...sx}
         {...props}
         className={clsx(sx.className, className)}
       />
     )
   }

   export {
     Sheet,
     SheetClose,
     SheetContent,
     SheetDescription,
     SheetFooter,
     SheetHeader,
     SheetOverlay,
     SheetPortal,
     SheetTitle,
     SheetTrigger,
     sheetStyles,
     type SheetSide,
   }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet"
```

```tsx
<Sheet>
  <SheetTrigger render={<Button variant="outline" />}>Open</SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Profile</SheetTitle>
      <SheetDescription>Update your name and username, then save.</SheetDescription>
    </SheetHeader>
  </SheetContent>
</Sheet>
```

## Composition

```text
Sheet
├── SheetTrigger
└── SheetContent          portal + overlay + popup
    ├── SheetHeader
    │   ├── SheetTitle
    │   └── SheetDescription
    └── SheetFooter
        └── SheetClose
```

`SheetContent` renders the portal, the overlay and the popup in one part. Reach
the overlay through `overlayProps`, or compose `SheetPortal` and `SheetOverlay`
yourself.

`SheetHeader` and `SheetFooter` carry their own padding, and the popup spaces
its children with a gap. A body between them needs only inline padding, so give
it a `VStack` with `paddingInline={4}`.

## Side

Set `side` on `SheetContent` to choose the edge the sheet slides in from:
`top`, `right`, `bottom` or `left`.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet"
import { HStack, VStack } from "@/components/ui/stack"

const sides = ["top", "right", "bottom", "left"] as const

const styles = stylex.create({
  short: { maxHeight: "50vh" },
})

export default function SheetSide() {
  return (
    <HStack gap={2} wrap="wrap" justify="center">
      {sides.map((side) => (
        <Sheet key={side}>
          <SheetTrigger render={<Button variant="outline" />}>{side}</SheetTrigger>
          <SheetContent
            side={side}
            xstyle={side === "top" || side === "bottom" ? styles.short : undefined}
          >
            <SheetHeader>
              <SheetTitle>Profile</SheetTitle>
              <SheetDescription>Update your name and username, then save.</SheetDescription>
            </SheetHeader>
            <VStack grow scrollable gap={2} paddingInline={4} className="no-scrollbar">
              {Array.from({ length: 10 }).map((_, index) => (
                <p key={index}>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute
                  irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
                  pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
                  officia deserunt mollit anim id est laborum.
                </p>
              ))}
            </VStack>
            <SheetFooter>
              <Button type="submit">Save changes</Button>
              <SheetClose render={<Button variant="outline" />}>Cancel</SheetClose>
            </SheetFooter>
          </SheetContent>
        </Sheet>
      ))}
    </HStack>
  )
}
```

A side sheet is `75%` of the viewport width, or `24rem` from `48rem` up. A top
or bottom sheet is the height of its content. Cap it with `maxHeight` through
`xstyle`, and make the body a flex child with `grow` and `overflow-y: auto`.
`VStack`'s `scrollable` sets both.

## No close button

Pass `showCloseButton={false}` to `SheetContent` to leave out the corner button.
Escape and a click outside still close the sheet.

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

export default function SheetNoCloseButton() {
  return (
    <Sheet>
      <SheetTrigger render={<Button variant="outline" />}>Open</SheetTrigger>
      <SheetContent showCloseButton={false}>
        <SheetHeader>
          <SheetTitle>Reading options</SheetTitle>
          <SheetDescription>
            There is no close button in the corner. Press Escape or click outside the sheet to close
            it.
          </SheetDescription>
        </SheetHeader>
      </SheetContent>
    </Sheet>
  )
}
```

## API reference

Pass `render` to replace a part's element or compose it with another component.

Every part wraps the Base UI `Dialog` part of the same name and accepts its
props. See the [Base UI reference](https://base-ui.com/react/components/dialog)
for the full list. Each styled part also takes `xstyle` and `className`.

### Sheet

| Prop                      | Type                               | Default |
| ------------------------- | ---------------------------------- | ------- |
| `open`                    | `boolean`                          | —       |
| `defaultOpen`             | `boolean`                          | `false` |
| `onOpenChange`            | `(open: boolean, details) => void` | —       |
| `modal`                   | `boolean \| "trap-focus"`          | `true`  |
| `disablePointerDismissal` | `boolean`                          | `false` |

### SheetContent

| Prop              | Type                                     | Default   |
| ----------------- | ---------------------------------------- | --------- |
| `side`            | `"top" \| "right" \| "bottom" \| "left"` | `"right"` |
| `showCloseButton` | `boolean`                                | `true`    |
| `overlayProps`    | `SheetOverlayProps`                      | —         |
| `initialFocus`    | `boolean \| RefObject \| (type) => …`    | —         |
| `finalFocus`      | `boolean \| RefObject \| (type) => …`    | —         |

### sheetStyles

The style map behind `SheetContent`, exported so the same box can be put on
another element.

| Key       | Description                                                 |
| --------- | ----------------------------------------------------------- |
| `content` | The fixed panel: the shared surface, shadow and transition  |
| `sides`   | One style per `side`, with the edge, size and closed offset |

`content` is a pair: `states.popupSurface` from `theme/states.ts` and the
panel's own box over it. The panel takes the surface's shadow a level deeper,
as the dialog does. There is no border. The shadow's hairline ring draws the edge
that faces the page, and the other three sides sit past the viewport.

### Data attributes

| Attribute                                  | On                | Effect                                       |
| ------------------------------------------ | ----------------- | -------------------------------------------- |
| `data-slot="sheet-content"`                | the popup         | Popup slot                                   |
| `data-slot="sheet-overlay"`                | the scrim         | Backdrop surface                             |
| `data-side`                                | the popup         | The `side` prop, `"right"` by default        |
| `data-starting-style`, `data-ending-style` | popup and overlay | Base UI writes them while the sheet animates |
| `data-open`, `data-closed`                 | popup and overlay | Base UI writes them                          |
