Sheet Dialog
A Dialog anchored to an edge of the viewport — the panel pattern variously
marketed as “sheet”, “side panel” or “drawer” (names that describe motion, not
a job: this is a dialog in every sense). It reuses the headless dialog and the
shared modal adapter unchanged; over Dialog it adds edge anchoring (side:
top / bottom / start / end), a slide-in animation, and an optional
draggable drag-to-dismiss gesture on the bottom and lateral sides.
start and end follow the reading direction, as the other layout of the
design system does: the panel sits at, slides in from and is dragged toward
the right edge in left-to-right text and the left edge in right-to-left text.
There are no physical left and right sides. The default is end.
Use it for a task the user finishes or cancels in context — filters, an edit form, a cart. It stays modal: for content that could live on its own page and merely happens to be shown alongside, routing a view into a Sheet Dialog is the application’s choice.
When to use which dialog
Section titled “When to use which dialog”- Dialog — generic modal for any content; the head of the family.
- Alert Dialog — an acknowledgement: a message with nothing to cancel (one button).
- Confirm Dialog — verify or accept before proceeding:
cancel stops, confirm proceeds (
urgentto interrupt). - Prompt Dialog — asks for a single value
(optional,
required, or gated byconfirmValue;urgentto interrupt). - Search Dialog — a quick search: search by keyword and pick from a list.
- Sheet Dialog — a task in an edge-anchored panel
(
sidevariant, optional drag-to-dismiss).
Import
Section titled “Import”<script> import SheetDialog from "@invisible-ui/svelte/SheetDialog.svelte";</script><script setup> import { SheetDialog } from "@invisible-ui/vue";</script>import { SheetDialog } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-sheet-dialog></ds-sheet-dialog>In React the regions are props: trigger, children (the body), footer,
icon, headerLead and headerActions. useSheetDialog gives the same
behaviour, drag included, for markup of your own:
<SheetDialog side="end" title="Filters" description="Refine the results." trigger="Open filters" headerActions={<Button variant="ghost">Reset</Button>} footer={<Button variant="primary">Apply</Button>}> <FilterForm /></SheetDialog>| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | "default" | "primary" | "secondary" | "ghost" | "danger" | "default" | Visual variant for the trigger Button. |
renderTrigger | boolean | true | Whether this component renders its own trigger button. Turn it off when the button belongs somewhere this panel cannot reach, an application header for instance: drive open yourself and name returnFocusTo, since there is no trigger left for focus to go back to (ADR 0013). |
returnFocusTo | string | undefined | undefined | CSS selector for the element focus returns to when there is no trigger. |
side | SheetDialogSide | "end" | Which edge the panel is anchored to. |
draggable | boolean | false | Show a grab handle and enable the drag-to-dismiss gesture. Available on the bottom and lateral sides (ignored on side="top"). |
open | boolean | false | Initial open state. |
title * | string | — | Accessible title naming the panel (required). |
description | string | undefined | undefined | Optional description, wired via aria-describedby. |
closeLabel | string | undefined | undefined | Accessible label for the close button. Defaults to the i18n catalog's "Close". |
closeButton | boolean | true | Show the close button at the trailing end of the header. |
initialFocus | string | undefined | undefined | CSS selector (within the panel) for the element to focus on open — e.g. "input" to land on a form's first field instead of the close button. |
onOpenChange | ((open: boolean) => void) | undefined | undefined | Called whenever the open state changes. |
trigger | Snippet | undefined | undefined | The trigger button's content. Defaults to the i18n catalog's label. |
icon | Snippet | undefined | undefined | Leading feedback icon in the header. |
headerLead | Snippet | undefined | undefined | Leading ghost button in the header, e.g. back. |
headerActions | Snippet | undefined | undefined | Actions before the close button. |
footer | Snippet | undefined | undefined | Footer actions. |
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | string | undefined | The trigger button's label. The trigger slot replaces it with markup. |
side | SheetDialogSide | "end" | Which edge the panel is anchored to. |
draggable | boolean | false | Show a grab handle and enable the drag-to-dismiss gesture. Available on the bottom and lateral sides (ignored on side="top"). |
open | boolean | false | Initial / controlled open state; bindable with v-model:open. |
title * | string | — | Accessible title naming the panel (required). |
description | string | undefined | Optional description, wired via aria-describedby. |
closeLabel | string | undefined | Accessible label for the close button. Defaults to the catalog's "Close". |
closeButton | boolean | true | Show the close button at the trailing end of the header. Default true. |
initialFocus | string | undefined | CSS selector (within the panel) for the element to focus on open, e.g. "input" to land on a form's first field instead of the close button. |
renderTrigger | boolean | true | Whether this component renders its own trigger button. Turn it off when the button belongs somewhere this panel cannot reach, an application header for instance: drive open yourself and name returnFocusTo, since there is no trigger left for focus to go back to (ADR 0013). |
returnFocusTo | string | undefined | CSS selector for the element focus returns to when there is no trigger. |
onOpenChange | (open: boolean) => void | undefined | Called whenever the open state changes. |
| Event | Payload |
|---|---|
update:open | open: boolean |
Slots: default, footer, headerActions, headerLead, icon, trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | ReactNode | — | The trigger button's content. Defaults to the catalog's "Open". |
renderTrigger | boolean | true | Whether this component renders its own trigger button. Turn it off when the button belongs somewhere this panel cannot reach, an application header for instance: drive open yourself and name returnFocusTo, since there is no trigger left for focus to go back to (ADR 0013). |
returnFocusTo | string | — | CSS selector for the element focus returns to when there is no trigger. |
side | SheetDialogSide | "end" | Which edge the panel is anchored to. |
draggable | boolean | false | Show a grab handle and enable the drag-to-dismiss gesture. Available on the bottom and lateral sides (ignored on side="top"). |
open | boolean | false | Initial / controlled open state. |
title * | string | — | Accessible title naming the panel (required). |
description | string | — | Optional description, wired via aria-describedby. |
closeLabel | string | — | Accessible label for the close button. Defaults to the catalog's "Close". |
closeButton | boolean | true | Show the close button at the trailing end of the header. |
initialFocus | string | — | CSS selector (within the panel) for the element to focus on open, e.g. "input" to land on a form's first field. |
icon | ReactNode | — | Leading feedback icon in the header. |
headerLead | ReactNode | — | Leading ghost button in the header, e.g. back. |
headerActions | ReactNode | — | Actions before the close button. |
footer | ReactNode | — | Footer actions. |
onOpenChange | (open: boolean) => void | — | Called whenever the open state changes. |
children | ReactNode | — | The body. |
| Attribute | Reactive | Description |
|---|---|---|
heading * | yes | |
description | yes | |
trigger | yes | |
trigger-variant | yes | |
side | yes | |
draggable | yes | |
open | yes | |
close-label | yes | |
close-button | yes | "false" drops the close button |
initial-focus | — | |
render-trigger | yes | |
return-focus-to | — | |
no-outside-close | — |
Reactive attributes re-render the element when they change after the first render.
Methods: notify(options), dismissNotice(id), clearNotices() (the status area, ADR 0016).
Emits: open-change with detail.open.
Snippets: trigger (the trigger button’s content), children (the body)
and an optional footer pinned to the panel’s end.
Accessibility
Section titled “Accessibility”role="dialog"witharia-modal="true", named bytitleand described by the optionaldescription. Focus moves into the panel on open (customize withinitialFocus), is trapped, and returns to the trigger on close.- Escape, the close button, or a backdrop press dismiss it; body scroll is locked while open.
- The drag handle is a pointer affordance only (
aria-hidden): keyboard and screen-reader users dismiss with Escape or the close button, so no functionality depends on the gesture. Release past a quarter of the panel’s extent — or a fast flick — dismisses; anything less snaps home. In right-to-left text a lateral panel is dragged toward the edge it sits on, as in left-to-right text. - Under
prefers-reduced-motionthe panel appears without sliding and a released drag snaps back at once.
Example
Section titled “Example”<SheetDialog side="bottom" draggable title="Account" description="Manage your account."> {#snippet trigger()}<span>Account</span>{/snippet} <button type="button">Sign out</button></SheetDialog>The Elements adapter uses heading instead of the global HTML title
attribute. Named light-DOM regions keep actions in the header and footer:
<ds-sheet-dialog side="end" heading="Filters" description="Refine the results." trigger="Open filters"> <button slot="header-actions" type="button">Reset</button> <form>…</form> <button slot="footer" type="submit">Apply</button></ds-sheet-dialog>Themeable via --ds-dialog-* (shared) plus --ds-sheet-dialog-size,
--ds-sheet-dialog-duration and --ds-sheet-dialog-handle.