Skip to main content

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​

SlotRequiredDescription
title-Drawer title rendered inside the header.
contentYesMain content rendered inside the drawer body. The drawer renders when at least one of content or title is non-empty.

Props​

PropTypeDefaultDescription
idstring-HTML id for the drawer. Trigger buttons reference it via aria-controls.
has_closebooleantrueWhether to render a close button in the header.
has_backdropbooleantrueWhether to render a dimming backdrop behind the drawer while it is open. Clicking the backdrop closes the drawer.
is_openboolean-Whether the drawer renders in the open state.
is_modalboolean-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.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.topAlignment-Anchored to the top.
.bottomAlignment-Anchored to the bottom.
.leftAlignment-Anchored to the left.
.rightAlignment-Anchored to the right.
.hiddenVisibility-Visually and semantically hidden (display: none).
.invisibleVisibility-Visually hidden, still takes layout space (visibility: hidden).
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.
.flatElevation-No elevation.
.raisedElevation-Slight elevation.
.elevatedElevationYesHigh elevation.

Attributes​

AttributeSet byRequiredDescription
data-drawerConsumerYesMarks an element as a drawer root. Required for the JS to enhance the element.
data-drawer-backdropConsumer-Opts in to a sibling dimming overlay rendered while the drawer is open.
data-drawer-backdrop-openScript-Set on the backdrop element while the drawer is open. Style hook only - never set by consumers.
data-drawer-scroll-lockScript-Set on <body> while any drawer with a backdrop is open. Style hook for scroll-lock behavior.

Events​

EventDirectionDescription
drawer-openedEmitsFired on the drawer element after it opens.
drawer-closedEmitsFired on the drawer element after it closes.
close-dismissListensListened on the drawer root. Closes the drawer when a descendant close button dispatches this event.

Examples​

Left​

Drawer sliding in from the left edge.

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, and aria-modal="true" announces it as a modal dialog
  • Reduced-motion disables the slide animation

Dependencies​

  • close - dismiss button used in the drawer header
  • modal - centered modal dialog built on the native <dialog> element
  • mobilenav - mobile navigation panel that lives inside a drawer