# Sheet ## Summary `Sheet` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for panel-style overlays, usually bottom-mounted or mobile-first, with trigger, content, and handle parts. `SheetClose` turns your own button into a close button; headings and layout are plain markup you compose yourself. `SheetContent` renders a native `` opened with `showModal()`, so the browser puts it in the top layer, makes the rest of the page inert, and draws the backdrop. It is the touch- and panel-oriented overlay in the family, especially when snap points or bottom-entry behavior matter. ## Imports ```tsx import { Sheet, SheetTrigger, SheetContent, SheetClose, SheetHandle, type SheetProps, } from '@vega-ui/react'; ``` ## Exported Types - `SheetProps` - `SheetTriggerProps` - `SheetHandleProps` - `SheetContentProps` - `SheetCloseProps` ## Minimal Composition ```tsx import { useId, type CSSProperties } from 'react'; import { Button, Heading, Icon, IconButton, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; export default function MinimalComposition() { const titleId = useId(); return (
Order summary
2 × Flat white, 1 × Almond croissant · $13.40
); } ``` ## Required Parts - `Sheet`: root state and context provider - `SheetTrigger`: open action surface - `SheetContent`: modal sheet surface ## Optional Parts - `SheetHandle`: drag or gesture affordance - `SheetClose`: closes the sheet when clicked; wraps your own button with `asChild` ## Your Own Markup - a heading whose `id` is passed to `SheetContent` as `aria-labelledby` (or `aria-label` on `SheetContent`); the sheet must have a name - action buttons that answer the sheet inside a `
` - a scrollable region: an element with `overflow: auto` ## Composition Order 1. `Sheet` 2. `SheetTrigger` 3. `SheetContent` 4. `SheetHandle` 5. Your heading, an optional `SheetClose`, and body ## Variants - Bottom-sheet layouts versus general panel layouts - Trigger-driven versus [controlled](https://vega-ui.dev/docs/glossary/#controlled) open state - Snap-point based sheets versus fully open sheets - `closedBy` on `SheetContent`: closed by any action, by `Escape` only, or not by the user at all - Dimmed versus transparent backdrop (`overlay` on `SheetContent`); the sheet stays modal either way - Mobile-first presentation versus broader cross-device panel usage ## Migrating From 2.x `SheetHeader` and `SheetMain` were removed: the library keeps only parts that carry behavior plain markup cannot express. `SheetContent` now has the padding they used to provide. - `SheetHeader` → a `Heading` with an `id`, referenced by `aria-labelledby` on `SheetContent` - `SheetMain` → plain content, or an element with `overflow: auto` for a scrollable region - New: `SheetClose`, a close part with no styles of its own (Sheet had no close button before) - `useSheetContext()` no longer returns `contentId`, and `SheetTrigger` no longer sets `aria-controls` ## Edge Cases - Validate gesture affordances on touch devices. - Snap points should be tested against real content height. - Nested overlays need focus restoration and stacking checks. - Non-closable sheets need especially clear exit paths. ## Common Mistakes - Leaving `SheetContent` without `aria-labelledby` or `aria-label`. - Treating a sheet like a desktop modal dialog. - Using snap points without checking content usability at each stop. - Forgetting to test gesture, focus, and dismissal together. ## Examples ### Basic #### Basic: share sheet with heading and close button The sheet fits its content and closes with the round button, a swipe down, a backdrop click or `Escape`. The heading names it through `aria-labelledby`, the address describes it through `aria-describedby`, and the copy result is announced through a `role="status"` line. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Heading, Icon, IconButton, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; import { CopyIcon, MailIcon, MessageCircleIcon, XIcon } from '@vega-ui/icons'; const link = 'https://maps.example.com/p/blue-harbor-cafe'; export default function SheetWithHeadingAndCloseButton() { const titleId = useId(); const descriptionId = useId(); const [copied, setCopied] = useState(false); const copy = async () => { await navigator.clipboard.writeText(link); setCopied(true); }; return ( setCopied(false)}>
Share Blue Harbor Cafe
12 Quay Street · Open until 22:00 {copied ? 'The link is on your clipboard.' : ''} ); } ``` ### Controlled/Stateful #### Controlled/Stateful: snap point in your state With `activeSnapPoint` and `onChangeActiveSnapPoint` the snap point lives in your state, so the Peek, Half and Full buttons move the sheet and a drag updates the pressed button. `height: 100%` makes the sheet as tall as the viewport, so all three snap points apply. ```tsx import { useId, useState } from 'react'; import { Button, Heading, Sheet, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; const snapPoints: Array<`${number}px` | number> = ['180px', 0.5, 1]; const snapLabels = ['Peek', 'Half', 'Full']; const stops = ['Central Station', 'Market Square', 'Harbour Bridge', 'Old Town', 'University', 'Science Park', 'Airport']; export default function ControlledSnapPoint() { const titleId = useId(); const [snapPoint, setSnapPoint] = useState(0); return ( setSnapPoint(0)}> Bus 42 · next in 4 min
{snapLabels.map((label, index) => ( ))}
    {stops.map((stop, index) => (
  1. {stop} {4 + index * 3} min
    2. ))}
); } ``` #### Controlled/Stateful: picker that closes on choice The sheet's `open` is controlled, so choosing a delivery slot stores it and closes the sheet in one handler. The trigger shows the current choice, and `aria-pressed` marks it inside the sheet. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Heading, Icon, IconButton, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; const slots = [ { id: 'asap', label: 'As soon as possible', detail: '25–35 min · $2.99' }, { id: '1830', label: 'Today, 18:30–19:00', detail: '$1.99' }, { id: '1900', label: 'Today, 19:00–19:30', detail: '$1.99' }, { id: '1930', label: 'Today, 19:30–20:00', detail: 'Free' }, ]; export default function MobileLikePickerSurface() { const titleId = useId(); const [open, setOpen] = useState(false); const [slot, setSlot] = useState(slots[0]); const choose = (next: typeof slots[number]) => { setSlot(next); setOpen(false); }; return (
Delivery time
{slots.map((item) => ( ))}
); } ``` ### Form/Integration #### Form/Integration: feedback form A `` with a number field limited by `min`, `max` and `step` and an optional note. The browser validates the tip, a valid submit is read with `FormData` and closes the sheet; on phones the sheet rises above the on-screen keyboard. ```tsx import { useId, useState, type CSSProperties, type FormEvent } from 'react'; import { Button, Heading, Icon, IconButton, Label, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, TextArea, TextField, TextFieldInput, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; export default function SheetWithFormContent() { const titleId = useId(); const tipId = useId(); const noteId = useId(); const [summary, setSummary] = useState(''); const onSubmit = (event: FormEvent) => { const data = new FormData(event.currentTarget); const note = String(data.get('note')).trim(); setSummary(`Tip $${data.get('tip')}${note ? ` · “${note}”` : ''}`); }; return (
How was your delivery?