Bottom Sheet

Material Design 3 bottom sheet for presenting actions and supporting content from the bottom edge of the viewport. Not intended for full-application navigation; use drawers or dedicated pages when users need to browse many destinations.

Basic Usage

Open a standard bottom sheet with header, content, and actions. This pattern keeps users in context while exposing short supporting tasks.

Open Standard Sheet

<ds-bottom-sheet id="sheet-standard" variant="standard">
  <div slot="header">
    <h2>Sheet Title</h2>
  </div>
  <p>Supporting content goes here.</p>
  <div slot="actions">
    <ds-button variant="text">Cancel</ds-button>
    <ds-button variant="text">Confirm</ds-button>
  </div>
</ds-bottom-sheet>

Initial Value

Pre-configure behavior with drag settings before opening.

Open Configured Sheet

<ds-bottom-sheet
  variant="standard"
  draggable="false"
  drag-threshold="150">
  <p>This sheet disables drag-to-dismiss.</p>
</ds-bottom-sheet>

Variants

Bottom sheets support standard and modal interaction patterns.

Standard

Open Standard Variant

Modal

<ds-bottom-sheet variant="modal">
  <p>Modal variant requires explicit close actions.</p>
</ds-bottom-sheet>

States

Control open and close state programmatically.

Open State Demo

Close State Demo

const sheet = document.querySelector('#sheet-state');
sheet.show();
sheet.close();

Interactive Example

Open and interact with the sheet to view emitted lifecycle events.

Open Interactive Sheet

Event log:

API

Attributes

Attribute	Type	Default	Description
`variant`	string	`standard`	`standard` or `modal`.
`open`	boolean	false	Controls whether the sheet is visible.
`draggable`	boolean	true	Enables drag-to-dismiss for standard variant.
`drag-threshold`	number	100	Drag distance in pixels required before close.

Events

Event	Detail	Description
`ds-bottom-sheet:open`	`{}`	Fired when the sheet opens.
`ds-bottom-sheet:close`	`{}`	Fired when the sheet closes.
`ds-bottom-sheet:drag`	`{ progress }`	Fired while dragging with progress from 0 to 1.

Methods

Method	Description
`show()`	Opens the sheet.
`close()`	Closes the sheet.

CSS Parts

Part	Description
`container`	Outer fixed-position host layer.
`scrim`	Background overlay layer.
`sheet`	Main bottom sheet surface.
`header`	Header slot wrapper.
`content`	Default content slot wrapper.
`actions`	Actions slot wrapper.

CSS Custom Properties

Property	Description
`--ds-bottom-sheet-max-width`	Maximum sheet width.
`--ds-bottom-sheet-max-height`	Maximum sheet height.
`--ds-bottom-sheet-header-padding`	Header padding (mapped to global spacing tokens).
`--ds-bottom-sheet-actions-gap`	Action row spacing (mapped to global spacing tokens).

Accessibility

Keyboard Interaction

Key	Context	Expected Result
`Tab` / `Shift+Tab`	Sheet open	Moves focus through controls within the sheet
`Escape`	Sheet open	Closes the sheet and restores focus to the trigger
`Enter` / `Space`	Focus on action button	Activates the focused action

Semantics

Sheet surface uses role="dialog" and aria-modal="true".
Focus is restored to the previously focused element on close.
Drag interactions support touch and pointer input and can be disabled.

Usage Guidelines

When to use: Use standard bottom sheets for supplemental actions and short non-destructive tasks that should not navigate away.
When not to use: Avoid bottom sheets for deep workflows, large forms, or complex navigation trees.
Composition: Use modal variant for higher-priority decisions requiring explicit confirmation. Keep action counts low and place primary action last.
Common mistakes: Overloading sheet content with long scrolling text. Tune drag-threshold when accidental dismissal is observed.