Search docs

Drawer

A panel that slides in from an edge of the screen, such as a detail panel.

By default, Drawer is a non-modal dialog: the rest of the page stays usable while it is open. With modal, it follows the Dialog (Modal) WAI-ARIA design pattern like Dialog.

Order #1042

Shipped on November 12 to Osaka.

Items
3
Total
Â¥12,800
import { component$, useStyles$ } from '@builder.io/qwik';
import { Drawer } from '@leve-ui/drawer';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  // Non-modal by default: the page stays usable while the panel is open
  return (
    <Drawer.Root class="drawer-default">
      <Drawer.Trigger class="drawer-default-trigger">Order details</Drawer.Trigger>
      <button type="button" class="drawer-default-trigger">
        Another page action
      </button>
      <Drawer.Content class="drawer-default-content">
        <Drawer.Title class="drawer-default-title">Order #1042</Drawer.Title>
        <Drawer.Description class="drawer-default-description">
          Shipped on November 12 to Osaka.
        </Drawer.Description>
        <dl class="drawer-default-list">
          <dt>Items</dt>
          <dd>3</dd>
          <dt>Total</dt>
          <dd>Â¥12,800</dd>
        </dl>
        <Drawer.Close class="drawer-default-close" aria-label="Close">
          <LuX class="drawer-default-icon" aria-hidden="true" />
        </Drawer.Close>
      </Drawer.Content>
    </Drawer.Root>
  );
});

When to use#

UseWhen
DrawerA panel that opens next to the content while the page stays usable, such as the details of a row in a table.
Drawer with modalA panel that blocks the page, such as the navigation menu on small screens.
DialogA task or decision that must be finished before going back to the page.
A plain <aside>A panel that is always visible and never opens or closes. It is part of the layout, not a dialog.

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/drawer

Anatomy#

import { Drawer } from '@leve-ui/drawer'; // or '@leve-ui/core'

<Drawer.Root>
  <Drawer.Trigger />
  <Drawer.Content>
    <Drawer.Title />
    <Drawer.Description />
    <Drawer.Close />
  </Drawer.Content>
</Drawer.Root>
PartElementDescription
Drawer.Root<div>Wraps the parts and holds the open state, modal and side.
Drawer.Trigger<button>The button that opens and closes the drawer. Use as to render another element or component.
Drawer.Content<dialog>The panel.
Drawer.Title<h2>The title that names the drawer.
Drawer.Description<p>The description of the drawer.
Drawer.Close<button>A button that closes the drawer. Use as to render another element or component.

A component passed to as on Drawer.Trigger or Drawer.Close must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.

Drawer.Content is a native <dialog>, rendered where you place it and shown above the page in the top layer. A non-modal drawer is a popover="manual" element shown with showPopover(); a modal drawer is opened with showModal(). side only sets data-side: place the panel and its animation with CSS, as in the demos. A modal drawer has a backdrop, styled with ::backdrop like Dialog.

Examples#

modal blocks the page: focus stays in the drawer, the page does not scroll, and clicking the backdrop closes it. side="left" sets data-side="left".

Navigation

Go to a section of the site.

API Reference#

Root#

PropDefaultType
ids–{ trigger?: string; content?: string; title?: string; description?: string }

Overrides the element IDs of the parts.

defaultOpenfalseboolean

Whether the drawer is open initially (uncontrolled). The drawer opens when the page resumes, since it is shown from the client.

bind:open–Signal<boolean>

A signal with the open state (controlled).

onOpenChange$–QRL<(open: boolean) => void>

Called when the drawer opens or closes by a user interaction.

modalfalseboolean

Whether the drawer is modal: it traps focus, blocks the page and closes on outside click, like a Dialog. By default the page stays usable while the drawer is open.

side'right''top' | 'right' | 'bottom' | 'left'

The edge of the screen the drawer is attached to. Only sets data-side; place it with CSS.

Also accepts all <div> attributes.

Data attributeValue
data-leve-drawerAlways present
data-state"open" | "closed"
data-side"top" | "right" | "bottom" | "left"

The open state is uncontrolled with defaultOpen, or controlled with bind:open. onOpenChange$ is called when the user opens or closes the drawer. The SSR HTML always renders the drawer closed: a drawer that is open initially opens when the page resumes.

Trigger#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-drawer-triggerAlways present
data-state"open" | "closed"

The trigger toggles the drawer: a non-modal drawer leaves it usable while open.

Content#

PropDefaultType
closeOnEscapetrueboolean

Whether Escape closes the drawer.

closeOnOutsideClicktrueboolean

Whether a pointer down on the backdrop closes a modal drawer. A non-modal drawer never closes on outside interaction.

Also accepts all <dialog> attributes.

Data attributeValue
data-leve-drawer-contentAlways present
data-state"open" | "closed"
data-side"top" | "right" | "bottom" | "left"

A non-modal drawer matches :popover-open while it is shown, and a modal drawer has the open attribute. Use them with @starting-style to animate the drawer when it appears.

Title#

No props of its own. Accepts all <h2> attributes.

Data attributeValue
data-leve-drawer-titleAlways present

Description#

No props of its own. Accepts all <p> attributes.

Data attributeValue
data-leve-drawer-descriptionAlways present

Close#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-drawer-closeAlways present
data-state"open" | "closed"

Accessibility#

There is no WAI-ARIA APG pattern for non-modal dialogs. A non-modal drawer is a role="dialog" without aria-modal, where focus can move freely between the drawer and the page (ADR 0028). With modal, Drawer complies with the Dialog (Modal) WAI-ARIA design pattern.

  • Drawer.Content renders aria-labelledby pointing to Drawer.Title, aria-describedby pointing to Drawer.Description, and aria-modal="true" only when modal.
  • Drawer.Trigger renders aria-haspopup="dialog", aria-expanded and aria-controls pointing to the Content.
  • When the drawer opens, focus moves to its first focusable element. When it closes, focus returns to the element that was focused before it opened, or to the Trigger. If a non-modal drawer closes while focus is elsewhere on the page, focus does not move.
  • A non-modal drawer does not trap focus or stop the page from scrolling, and does not close when the page is clicked. A modal drawer does all three.
  • If Drawer.Close only contains an icon, give it an aria-label.

Keyboard Interactions#

KeyDescription
TabNon-modal: moves focus through the drawer and on to the page. Modal: cycles through the focusable elements in the drawer.
Shift + TabMoves focus backwards, in the same way.
EscapeCloses the drawer, unless closeOnEscape is false.