Skip to content

Drawer ​

A slide-in panel that overlays page content from any edge of the screen. Built on the native <dialog> element for correct top-layer stacking, focus trapping, and Escape-to-close behavior.

Placements ​

Use open as the controlled state and update it from open-change; use default-open only to initialize an uncontrolled drawer. Use placement to control which edge the drawer slides in from: left, right (default), top, or bottom.

Full width

Sizes ​

Full width

Use size="content" with placement="bottom" or placement="top" for a content-sized sheet. Short content fits naturally. The panel stops at the viewport height minus var(--size-12), then scrolls its body while the header and footer remain visible. Leave detents unset for a two-state reading sheet.

Use the header slot to replace the default title bar and the footer slot for action buttons. A dismissible drawer with no title shows its close button with no header divider, so content-first drawers keep a light top edge.

Full width

Drag Handle Placement ​

The drag handle is a decorative pointer-gesture affordance, not a keyboard control. Use the Close button or Escape to dismiss with a keyboard. Preventing a swipe close-request restores the panel without losing its contents.

Use drag-handle-placement to control whether the swipe handle sits inset inside the panel edge (default) or outside it.

Full width

Touch Swiping from Content ​

Start a fresh outward touch swipe on the drawer body to drag the panel toward closed. The body and any nested scroll areas under your finger must already be at their closing boundary. If your swipe scrolls content to that boundary, lift your finger and swipe again; the drawer does not take over an active native scroll.

PlacementOutward swipeRequired content boundary
bottomDownTop
topUpBottom
right (LTR)RightLeft
left (LTR)LeftRight

In RTL, side drawers mirror their physical edge, swipe direction, and horizontal boundary. Side drawers keep ordinary vertical scrolling. Non-scrollable content can start a drag immediately.

Release uses the same distance threshold, fling projection, spring, and detents as the handle. A short drag settles back; a canceled gesture never dismisses. Content dismissal emits close-request with reason swipe, so you can prevent it without losing content or draft state. persistent does not disable swipe dismissal.

Buttons, links, fields, editable content, and Refine's gesture-driven carousel, list item, pull-to-refresh, sidebar, toast, and nested drawer keep their own interactions. Header and footer content do not initiate body dragging. Mouse selection, wheel scrolling, and keyboard scrolling do not dismiss the drawer; native pinch zoom remains available.

A card picker keeps horizontal swipes for browsing. In a bottom drawer, a fresh downward swipe on ordinary card content at the scroll chain's top boundary requests dismissal; a top drawer accepts the corresponding upward swipe at the bottom boundary. Side drawers do not claim horizontal swipes started inside a picker. The drawer owns the cancelable close request, and dismissal never changes card selection. Mark custom picker subtrees with data-no-swipe to protect them from both picker browsing and drawer dismissal.

Opt out for the whole drawer or protect a custom gesture surface:

html
<ore-drawer placement="bottom" title="Reading" swipe-from-content="false">
  <p>Scroll or select this content; use the handle or Close button to dismiss.</p>
</ore-drawer>

<ore-drawer placement="right" title="Details">
  <p>You can start an outward touch drag here.</p>
  <div data-no-swipe>
    <p>This subtree owns its touch gestures.</p>
  </div>
</ore-drawer>

Detents (Snap Points) ​

On a bottom or top drawer, detents turns the panel into a sheet that can rest partway open. Pass comma-separated fractions of the panel size — "0.5,0.75" means the dragged panel can snap to half-open and three-quarters-open on its way between fully open and closed.

Full width

A drag released between two snap points settles to the nearer one, and a fling is projected forward with its release velocity before choosing a stop — so a quick flick carries through to the next detent (or closes) while a slow release settles without overshoot. Every rest position, including each detent, stays fully opaque so the sheet is readable at any stop. Detents are the bottom-sheet pattern only: setting detents on a left or right drawer warns and is ignored.

Backdrop Styles (backdrop) ​

Use backdrop to match dialog behavior:

  • opaque (default): dim overlay
  • blur: dim + blur
  • transparent: no overlay
Full width

Closing from Content ​

Mark any element inside the drawer with data-drawer-close and clicking it closes the drawer — nav rows, saved records, a footer "Done" button. No per-button wiring. The click takes the same path as the close button: a cancelable close-request with reason: "trigger" fires first, so validation logic can still keep the drawer open.

Full width

Listening to Events ​

html
<ore-drawer id="my-drawer" label="Notifications" dismissible>
  <p>You have no new notifications.</p>
</ore-drawer>

<script type="module">
  import '@vielzeug/refine/drawer';

  const drawer = document.getElementById('my-drawer');
  drawer.addEventListener('open-change', (e) => console.log('drawer open:', e.detail.open, e.detail.reason));
  drawer.addEventListener('close-request', (e) => {
    if (e.detail.reason === 'outsideClick') {
      console.log('close requested from backdrop click');
    }
  });
</script>

Recipes ​

Complete patterns assembled from the primitives above. Each one relies on data-drawer-close for content-driven dismissal instead of hand-wired listeners.

Record detail ​

A detail drawer: identity row in the header slot, key/value facts in the body, row actions in the footer.

Full width

Filters ​

A filter drawer: controls in the body, Reset and Apply in the footer. Apply closes the drawer through data-drawer-close; the host app listens for open-change to read the controls when it closes.

Full width

Quick-action sheet ​

A bottom sheet: size="content" fits the actions, detents lets a dragged sheet rest half-open, and every action closes the sheet on its way.

Full width

API Reference ​

Attributes ​

AttributeTypeDefaultDescription
openbooleanN/AControlled visibility
default-openbooleanfalseInitial visibility when open is not provided
placement'left' | 'right' | 'top' | 'bottom''right'Edge the drawer slides in from
size'sm' | 'lg' | 'full' | 'content'unsetSize preset; content fits top/bottom sheets to content with bounded body scrolling
detentsstringN/AComma-separated drag snap points as fractions of panel size (e.g. '0.5,0.75'); bottom/top placement only
titlestringN/AVisible header title text
labelstringN/AAccessible name (aria-label); also shown as the header title when title is not set
drag-handle-placement'outside' | 'inset''inset'Position of the swipe drag handle
swipe-from-contentbooleantrueAllow outward touch dragging from the body when its scroll chain starts at the closing boundary
dismissiblebooleantrueShows a close (×) button in the header
backdrop'opaque' | 'blur' | 'transparent''opaque'Backdrop style, matching ore-dialog
modalbooleantrueWhen false, the drawer is modeless: no backdrop, the page stays interactive, and Escape closes only from inside
persistentbooleanfalsePrevents backdrop click from requesting close

Beyond these attributes, any element inside the drawer's content — in the body or the slots — accepts data-drawer-close: clicking it closes the drawer through the same cancelable close-request path as the close button (reason trigger).

A modeless drawer (modal="false") is for inspectors and side panels that edit what is behind them: the page keeps receiving input, no backdrop veil is painted, and the panel floats above the content. Because the page is never inert, focus never moves into the panel on open; Escape closes the drawer only while the focus is inside it, so give the user a visible close button (the default) and listen to open-change to react to dismissal. A control inside the panel that consumes Escape itself — an open ore-select closing its dropdown — swallows the key, so the first Escape dismisses the dropdown and only the next one closes the drawer.

Add data-no-swipe to a body descendant to exclude its entire subtree from content dragging. This does not disable native scrolling or clicks. Set swipe-from-content="false" on the drawer to disable all content dragging; the handle remains available.

Slots ​

SlotDescription
(default)Drawer body content
headerReplace the default header bar (overrides the title text)
footerFooter area, typically used for action buttons

Events ​

EventDetailDescription
open-change{ open: boolean, reason: string }Fired whenever the drawer opens or closes
close-request{ placement: 'left' | 'right' | 'top' | 'bottom', reason: 'trigger' | 'escape' | 'outsideClick' | 'swipe' | 'programmatic' }Fired before close and can be prevented

CSS Custom Properties ​

PropertyDescription
--drawer-backdrop-bgBackdrop veil color (default --overlay-veil)
--drawer-bgPanel background color
--drawer-sizePanel width (horizontal) or height (vertical)
--drawer-shadowPanel box shadow
--drawer-panel-blurPanel backdrop blur amount

Accessibility ​

The drawer component follows the WAI-ARIA Dialog Pattern best practices.

The panel uses role="dialog" with aria-modal="true" to signal that content outside is inert. Always provide a label attribute to give screen readers a descriptive panel title. When dismissible is set, the close button carries aria-label="Close" automatically. With modal="false" the drawer reports aria-modal="false": the page stays interactive and nothing is inerted, so keyboard users reach the panel with regular Tab navigation instead of a focus trap.

Tab and Shift+Tab move focus between focusable elements inside the panel. Escape closes the drawer when dismissible is set. In modal mode, focus moves into the panel on open and returns to the trigger element on close; in modeless mode focus stays where it is and Escape closes only from inside the panel.

  • Dialog: modal dialog for confirmations and focused tasks