Drawer
Sliding panel anchored to a screen edge. Non-modal by default - the underlying page stays interactive and scrollable while the drawer is open. Renders as a <div role="dialog"> enhanced by drawer.js, which manages open/close state, an optional dimming backdrop (has_backdrop prop), and focus return to the triggering element. Opt into a modal presentation with is_modal, which sets aria-modal="true", forces the backdrop on, and traps Tab focus inside the drawer while it is open.
Usage
When to use
- Mobile navigation that slides in from the side
- Secondary filters or details panels anchored to the edge
- Shopping carts or quick-view panels
When not to use
- Centered focused dialogs - use a modal
- Non-blocking notifications - use an announcement
- Small floating panels tied to a trigger - use a dropdown
Do
- Give the drawer a clear header and close button
- Pick a direction that matches the content's role (start/end for navigation; top/bottom for filters on mobile)
- Return focus to the invoking element on close
Don't
- Stack drawers on top of each other
- Use a drawer for content that should persist between pages
API
Slots
| Slot | Required | Description |
|---|---|---|
title | - | Drawer title rendered inside the header. |
content | Yes | Main content rendered inside the drawer body. The drawer renders when at least one of content or title is non-empty. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | - | HTML id for the drawer. Trigger buttons reference it via aria-controls. |
has_close | boolean | true | Whether to render a close button in the header. |
has_backdrop | boolean | true | Whether to render a dimming backdrop behind the drawer while it is open. Clicking the backdrop closes the drawer. |
is_open | boolean | - | Whether the drawer renders in the open state. |
is_modal | boolean | - | Modal mode: renders a backdrop, sets aria-modal="true", and traps focus within the drawer while open (Tab cycles inside it); focus returns to the invoking element on close. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.top | Alignment | - | Anchored to the top. |
.bottom | Alignment | - | Anchored to the bottom. |
.left | Alignment | - | Anchored to the left. |
.right | Alignment | - | Anchored to the right. |
.hidden | Visibility | - | Visually and semantically hidden (display: none). |
.invisible | Visibility | - | Visually hidden, still takes layout space (visibility: hidden). |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
.flat | Elevation | - | No elevation. |
.raised | Elevation | - | Slight elevation. |
.elevated | Elevation | Yes | High elevation. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-drawer | Consumer | Yes | Marks an element as a drawer root. Required for the JS to enhance the element. |
data-drawer-backdrop | Consumer | - | Opts in to a sibling dimming overlay rendered while the drawer is open. |
data-drawer-backdrop-open | Script | - | Set on the backdrop element while the drawer is open. Style hook only - never set by consumers. |
data-drawer-scroll-lock | Script | - | Set on <body> while any drawer with a backdrop is open. Style hook for scroll-lock behavior. |
Events
| Event | Direction | Description |
|---|---|---|
drawer-opened | Emits | Fired on the drawer element after it opens. |
drawer-closed | Emits | Fired on the drawer element after it closes. |
close-dismiss | Listens | Listened on the drawer root. Closes the drawer when a descendant close button dispatches this event. |
Examples
Left
Drawer sliding in from the left edge.
Right
Drawer sliding in from the right edge.
Top
Drawer sliding in from the top of the viewport.
Bottom
Drawer sliding in from the bottom of the viewport.
Multiple instances
Multiple drawers on the same page triggered by separate buttons.
No backdrop
has_backdrop off, so the page behind the panel stays visible and interactive.
With backdrop
has_backdrop on, which dims the page behind the panel and makes an outside click dismiss it.
Accessibility
- WCAG 2.2 AA
- Escape key closes the drawer
- Focus moves into the drawer when it opens and returns to the invoking element when it closes
- With
is_modal, focus is trapped inside the drawer while open (Tab cycles within it), the backdrop is forced on, andaria-modal="true"announces it as a modal dialog - Reduced-motion disables the slide animation
Dependencies
- close - dismiss button used in the drawer header