OverlaysReact

Drawer

A panel that slides in from the edge of the screen.

Rendered by React 19.3.1

Loading React…

import { Drawer } from '@hamur/react/drawer'

export default function DrawerExample() {
  return (
    <Drawer.Root swipeDirection="right">
      <Drawer.Trigger className="button">
        Open drawer
      </Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Backdrop className="backdrop drawer-backdrop" />
        <Drawer.Viewport className="drawer-viewport">
          <Drawer.Popup className="drawer">
            <Drawer.Content>
              <Drawer.Title className="dialog-title">
                Filters
              </Drawer.Title>
              <Drawer.Description className="muted">
                Narrow the list down. Swipe right or press Esc to close.
              </Drawer.Description>
              <div className="actions">
                <Drawer.Close className="button">
                  Done
                </Drawer.Close>
              </div>
            </Drawer.Content>
          </Drawer.Popup>
        </Drawer.Viewport>
      </Drawer.Portal>
    </Drawer.Root>
  )
}

579Tests passing in React · 0 failing

45.7 KiBSize

1.90 msOpen

2.20 msClose

18.0 msOpenMutations

21.0 msCloseMutations

0.78 MiBMemory

productdevbook and 13 upstream authors8 commits · last Nov 4

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Drawer.Root>
  <Drawer.Trigger />
  <Drawer.Portal>
    <Drawer.Backdrop />
    <Drawer.Viewport>
      <Drawer.Popup>
        <Drawer.Content>
          <Drawer.Title />
          <Drawer.Description />
          <Drawer.Close />
        </Drawer.Content>
      </Drawer.Popup>
    </Drawer.Viewport>
  </Drawer.Portal>
</Drawer.Root>

// Not in this example: Drawer.Indent, Drawer.IndentBackground, Drawer.Provider, Drawer.SwipeArea, Drawer.VirtualKeyboardProvider

Examples

Position

swipeDirection matches the side the drawer comes from.

DrawerPosition.tsx

import { Drawer } from '@hamur/react/drawer'

export default function DrawerPositionExample() {
  return (
    <Drawer.Root>
      <Drawer.Trigger className="button">Open bottom drawer</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Backdrop className="backdrop drawer-backdrop" />
        <Drawer.Viewport className="sheet-viewport">
          <Drawer.Popup className="sheet">
            <div className="sheet-handle" />
            <Drawer.Content className="sheet-content">
              <Drawer.Title className="sheet-title">Notifications</Drawer.Title>
              <Drawer.Description className="sheet-description">
                You are all caught up. Good job!
              </Drawer.Description>
              <div className="sheet-actions">
                <Drawer.Close className="button">Close</Drawer.Close>
              </div>
            </Drawer.Content>
          </Drawer.Popup>
        </Drawer.Viewport>
      </Drawer.Portal>
    </Drawer.Root>
  )
}

Nested

A drawer opens another; data-nested-drawer-open and --nested-drawers style the ones behind.

DrawerNested.tsx

import { Drawer } from '@hamur/react/drawer'

export default function DrawerNestedExample() {
  return (
    <Drawer.Root>
      <Drawer.Trigger className="button">Open drawer stack</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Backdrop className="backdrop drawer-backdrop" />
        <Drawer.Viewport className="sheet-viewport">
          <Drawer.Popup className="sheet sheet-stack">
            <div className="sheet-handle" />
            <Drawer.Content className="sheet-content">
              <Drawer.Title className="sheet-title">Account</Drawer.Title>
              <Drawer.Description className="sheet-description">
                Nested drawers can be styled to stack, while each drawer remains independently focus
                managed.
              </Drawer.Description>

              <div className="sheet-actions end">
                <div className="sheet-actions-left">
                  <Drawer.Root>
                    <Drawer.Trigger className="button">Security settings</Drawer.Trigger>
                    <Drawer.Portal>
                      <Drawer.Viewport className="sheet-viewport">
                        <Drawer.Popup className="sheet sheet-stack">
                          <div className="sheet-handle" />
                          <Drawer.Content className="sheet-content">
                            <Drawer.Title className="sheet-title">Security</Drawer.Title>
                            <Drawer.Description className="sheet-description">
                              Review sign-in activity and update your security preferences.
                            </Drawer.Description>

                            <ul className="sheet-list">
                              <li>Passkeys enabled</li>
                              <li>2FA via authenticator app</li>
                              <li>3 signed-in devices</li>
                            </ul>

                            <div className="sheet-actions end">
                              <div className="sheet-actions-left">
                                <Drawer.Root>
                                  <Drawer.Trigger className="button">
                                    Advanced options
                                  </Drawer.Trigger>
                                  <Drawer.Portal>
                                    <Drawer.Viewport className="sheet-viewport">
                                      <Drawer.Popup className="sheet sheet-stack">
                                        <div className="sheet-handle" />
                                        <Drawer.Content className="sheet-content">
                                          <Drawer.Title className="sheet-title">
                                            Advanced
                                          </Drawer.Title>
                                          <Drawer.Description className="sheet-description">
                                            This drawer is taller to demonstrate variable-height
                                            stacking.
                                          </Drawer.Description>

                                          <div className="sheet-field">
                                            <label htmlFor="device-name">Device name</label>
                                            <input
                                              id="device-name"
                                              className="input"
                                              defaultValue="Personal laptop"
                                            />
                                          </div>

                                          <div className="sheet-field">
                                            <label htmlFor="notes">Notes</label>
                                            <textarea
                                              id="notes"
                                              className="textarea"
                                              defaultValue="Rotate recovery codes and revoke older sessions."
                                              rows={3}
                                            />
                                          </div>

                                          <div className="sheet-actions end">
                                            <Drawer.Close className="button">Done</Drawer.Close>
                                          </div>
                                        </Drawer.Content>
                                      </Drawer.Popup>
                                    </Drawer.Viewport>
                                  </Drawer.Portal>
                                </Drawer.Root>
                              </div>

                              <Drawer.Close className="button">Close</Drawer.Close>
                            </div>
                          </Drawer.Content>
                        </Drawer.Popup>
                      </Drawer.Viewport>
                    </Drawer.Portal>
                  </Drawer.Root>
                </div>

                <Drawer.Close className="button">Close</Drawer.Close>
              </div>
            </Drawer.Content>
          </Drawer.Popup>
        </Drawer.Viewport>
      </Drawer.Portal>
    </Drawer.Root>
  )
}

Snap Points

snapPoints stops a bottom sheet at preset heights.

DrawerSnapPoints.tsx

import * as React from 'react'
import { Drawer } from '@hamur/react/drawer'

const TOP_MARGIN_REM = 1
const VISIBLE_SNAP_POINTS_REM = [30]

function toViewportSnapPoint(heightRem: number) {
  return `${heightRem + TOP_MARGIN_REM}rem`
}

const snapPoints = [...VISIBLE_SNAP_POINTS_REM.map(toViewportSnapPoint), 1]

export default function DrawerSnapPointsExample() {
  return (
    <Drawer.Root snapPoints={snapPoints}>
      <Drawer.Trigger className="button">Open snap drawer</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Backdrop className="backdrop drawer-backdrop" />
        <Drawer.Viewport className="snap-viewport">
          <Drawer.Popup
            className="snap-sheet"
            style={{ '--top-margin': `${TOP_MARGIN_REM}rem` } as React.CSSProperties}
          >
            <div className="snap-drag">
              <div className="sheet-handle" />
              <Drawer.Title className="sheet-title">Snap points</Drawer.Title>
            </div>
            <Drawer.Content className="snap-scroll">
              <div className="sheet-content">
                <Drawer.Description className="sheet-description">
                  Drag the sheet to snap between a compact peek and a near full-height view.
                </Drawer.Description>
                <div className="snap-cards" aria-hidden>
                  {Array.from({ length: 20 }, (_, index) => (
                    <div className="snap-card" key={index} />
                  ))}
                </div>
                <div className="sheet-actions end">
                  <Drawer.Close className="button">Close</Drawer.Close>
                </div>
              </div>
            </Drawer.Content>
          </Drawer.Popup>
        </Drawer.Viewport>
      </Drawer.Portal>
    </Drawer.Root>
  )
}

Virtual Keyboard Aware

VirtualKeyboardProvider keeps the focused field visible above a software keyboard.

DrawerVirtualKeyboardAware.tsx

import { Drawer } from '@hamur/react/drawer'

const fields = [
  ['Name', 'Ada Lovelace'],
  ['Phone', '+1 (555) 123-4567'],
  ['Street address', '12 Computing Way'],
  ['Apartment', 'Unit 4B'],
  ['City', 'San Francisco'],
  ['Postal code', '94107'],
  ['Delivery window', 'After 6 PM'],
  ['Backup contact', 'Grace Hopper'],
]

export default function DrawerVirtualKeyboardAwareExample() {
  return (
    <Drawer.Root>
      <Drawer.Trigger className="button">Open keyboard-aware drawer</Drawer.Trigger>
      <Drawer.VirtualKeyboardProvider>
        <Drawer.Portal>
          <Drawer.Backdrop className="backdrop drawer-backdrop" />
          <Drawer.Viewport className="vk-viewport">
            <Drawer.Popup className="vk-sheet">
              <div className="vk-header">
                <div className="sheet-handle" />
                <div className="vk-header-actions">
                  <Drawer.Close className="button">Cancel</Drawer.Close>
                  <Drawer.Title className="sheet-title">Delivery details</Drawer.Title>
                  <Drawer.Close className="button">Save</Drawer.Close>
                </div>
              </div>

              <Drawer.Content className="vk-scroll">
                <div className="vk-form">
                  {fields.map(([label, placeholder]) => (
                    <label className="vk-field" key={label}>
                      <span>{label}</span>
                      <input className="input" placeholder={placeholder} type="text" />
                    </label>
                  ))}

                  <label className="vk-field">
                    <span>Instructions</span>
                    <textarea
                      className="textarea"
                      placeholder="Gate code, drop-off spot, or anything else the driver should know"
                    />
                  </label>
                </div>
              </Drawer.Content>

              <div className="vk-footer-slot">
                <div className="vk-footer">
                  <label className="vk-composer">
                    <span>Delivery note</span>
                    <input className="input" placeholder="Add a note for the driver" type="text" />
                  </label>
                </div>
              </div>
            </Drawer.Popup>
          </Drawer.Viewport>
        </Drawer.Portal>
      </Drawer.VirtualKeyboardProvider>
    </Drawer.Root>
  )
}

Indent Provider

Provider, Indent and IndentBackground scale the page down while a drawer is open.

DrawerIndentProvider.tsx

import * as React from 'react'
import { Drawer } from '@hamur/react/drawer'

export default function DrawerIndentProviderExample() {
  const [portalContainer, setPortalContainer] = React.useState<HTMLDivElement | null>(null)

  return (
    <Drawer.Provider>
      <div className="indent-root" ref={setPortalContainer}>
        <Drawer.IndentBackground className="indent-background" />
        <Drawer.Indent className="indent">
          <div className="indent-center">
            <Drawer.Root modal={false}>
              <Drawer.Trigger className="button">Open drawer</Drawer.Trigger>
              <Drawer.Portal container={portalContainer}>
                <Drawer.Backdrop className="backdrop drawer-backdrop contained" />
                <Drawer.Viewport className="sheet-viewport contained">
                  <Drawer.Popup className="sheet">
                    <div className="sheet-handle" />
                    <Drawer.Content className="sheet-content">
                      <Drawer.Title className="sheet-title">Notifications</Drawer.Title>
                      <Drawer.Description className="sheet-description">
                        You are all caught up. Good job!
                      </Drawer.Description>
                      <div className="sheet-actions">
                        <Drawer.Close className="button">Close</Drawer.Close>
                      </div>
                    </Drawer.Content>
                  </Drawer.Popup>
                </Drawer.Viewport>
              </Drawer.Portal>
            </Drawer.Root>
          </div>
        </Drawer.Indent>
      </div>
    </Drawer.Provider>
  )
}

modal off and disablePointerDismissal keep the page usable and the drawer open.

DrawerNonModal.tsx

import { Drawer } from '@hamur/react/drawer'

export default function DrawerNonModalExample() {
  return (
    <Drawer.Root swipeDirection="right" modal={false} disablePointerDismissal>
      <Drawer.Trigger className="button">Open non-modal drawer</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Viewport className="drawer-viewport">
          <Drawer.Popup className="drawer">
            <Drawer.Content>
              <Drawer.Title className="dialog-title">Non-modal drawer</Drawer.Title>
              <Drawer.Description className="muted">
                This drawer does not trap focus and ignores outside clicks. Use the close button or
                swipe to dismiss it.
              </Drawer.Description>
              <div className="actions">
                <Drawer.Close className="button">Close</Drawer.Close>
              </div>
            </Drawer.Content>
          </Drawer.Popup>
        </Drawer.Viewport>
      </Drawer.Portal>
    </Drawer.Root>
  )
}

Swipe Area

SwipeArea along the edge opens the drawer with a swipe.

DrawerSwipeArea.tsx

import * as React from 'react'
import { Drawer } from '@hamur/react/drawer'

export default function DrawerSwipeAreaExample() {
  const [portalContainer, setPortalContainer] = React.useState<HTMLDivElement | null>(null)

  return (
    <div className="swipe-root" ref={setPortalContainer}>
      <Drawer.Root swipeDirection="right" modal={false}>
        <Drawer.SwipeArea className="swipe-area">
          <span className="swipe-label">Swipe here</span>
        </Drawer.SwipeArea>
        <div className="swipe-center">
          <p className="swipe-hint">Swipe from the right edge to open the drawer.</p>
        </div>
        <Drawer.Portal container={portalContainer}>
          <Drawer.Backdrop className="backdrop drawer-backdrop contained" />
          <Drawer.Viewport className="drawer-viewport contained">
            <Drawer.Popup className="drawer">
              <Drawer.Content>
                <Drawer.Title className="dialog-title">Library</Drawer.Title>
                <Drawer.Description className="muted">
                  Swipe from the edge whenever you want to jump back into your playlists.
                </Drawer.Description>
                <div className="actions">
                  <Drawer.Close className="button">Close</Drawer.Close>
                </div>
              </Drawer.Content>
            </Drawer.Popup>
          </Drawer.Viewport>
        </Drawer.Portal>
      </Drawer.Root>
    </div>
  )
}

API reference

31 props across 15 parts, in React syntax. className, style, render are listed once, under Shared props.

Backdrop`Drawer.Backdrop`

An overlay displayed beneath the popup. Renders a <div>.

Backdrop props
Prop	Type	Default
`forceRender`Whether the backdrop is forced to render even when nested.	`boolean`	`false`

Backdrop data attributes
Data attribute	Description
`data-open`	Present when the drawer is open.
`data-closed`	Present when the drawer is closed.
`data-starting-style`	Present when the drawer begins animating in.
`data-ending-style`	Present when the drawer is animating out.

Backdrop CSS variables
CSS variable	Description
`--drawer-swipe-progress`	The swipe progress of the drawer gesture.

Close`Drawer.Close`

A button that closes the drawer. Renders a <button>.

Close props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

Close data attributes
Data attribute	Description
`data-disabled`	Present when the button is disabled.

Content`Drawer.Content`

A container for the drawer contents. Renders a <div>.

Description`Drawer.Description`

A paragraph with additional information about the drawer. Renders a <p>.

Indent`Drawer.Indent`

A wrapper element intended to contain your app's main UI. Applies data-active when any drawer within the nearest <Drawer.Provider> is open. Renders a <div>.

IndentBackground`Drawer.IndentBackground`

An element placed before <Drawer.Indent> to render a background layer that can be styled based on whether any drawer is open. Renders a <div>.

Popup`Drawer.Popup`

A container for the drawer contents. Renders a <div>.

Popup props
Prop	Type	Default
`initialFocus`Determines the element to focus when the drawer is opened.	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`
`finalFocus`Determines the element to focus when the drawer is closed.	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`

Popup data attributes
Data attribute	Description
`data-open`	Present when the drawer is open.
`data-closed`	Present when the drawer is closed.
`data-starting-style`	Present when the drawer begins animating in.
`data-ending-style`	Present when the drawer is animating out.
`data-expanded`	Present when the drawer is at the expanded (full-height) snap point.
`data-nested-drawer-open`	Present when a nested drawer is open.
`data-nested-drawer-swiping`	Present when a nested drawer is being swiped.
`data-swipe-dismiss`	Present when the drawer is dismissed by swiping.
`data-swipe-direction`	Indicates the swipe direction.
`data-swiping`	Present when the drawer is being swiped.

Popup CSS variables
CSS variable	Description
`--nested-drawers`	The number of nested drawers that are currently open.
`--drawer-height`	The height of the drawer popup.
`--drawer-frontmost-height`	The height of the frontmost open drawer in the current nested drawer stack.
`--drawer-swipe-movement-x`	The swipe movement on the X axis.
`--drawer-swipe-movement-y`	The swipe movement on the Y axis.
`--drawer-snap-point-offset`	The snap point offset used for translating the drawer.
`--drawer-swipe-strength`	A scalar (0.1-1) used to scale the swipe release transition duration in CSS.

Portal`Drawer.Portal`

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div>.

Portal props
Prop	Type	Default
`container`A parent element to render the portal element into.	`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`	`—`
`keepMounted`Whether to keep the portal mounted in the DOM while the popup is hidden.	`boolean`	`false`

Provider`Drawer.Provider`

Provides a shared context for coordinating global Drawer UI, such as indent/background effects based on whether any Drawer is open. Doesn’t render its own element.

Provider props
Prop	Type	Default
`children`	`React.ReactNode`	`—`

Root`Drawer.Root`

Groups all parts of the drawer. Doesn’t render its own element.

Root props
Prop	Type	Default
`defaultOpen`Whether the drawer is initially open.	`boolean`	`false`
`open`Whether the drawer is currently open.	`boolean`	`—`
`onOpenChange`Event handler called when the drawer is opened or closed.	`((open: boolean, eventDetails: DrawerRootChangeEventDetails) => void)`	`—`
`snapPoints`Snap points used to position the drawer.	`DrawerSnapPoint[]`	`—`
`defaultSnapPoint`The initial snap point value when uncontrolled.	`DrawerSnapPoint \| null`	`—`
`snapPoint`The currently active snap point.	`DrawerSnapPoint \| null`	`—`
`onSnapPointChange`Callback fired when the snap point changes.	`((snapPoint: DrawerSnapPoint \| null, eventDetails: DrawerRootSnapPointChangeEventDetails) => void)`	`—`
`actionsRef`A ref to imperative actions.	`React.RefObject<DrawerRootActions \| null>`	`—`
`defaultTriggerId`ID of the trigger that the drawer is associated with.	`string \| null`	`—`
`disablePointerDismissal`Whether to prevent the drawer from closing on outside presses.	`boolean`	`false`
`handle`A handle to associate the drawer with a trigger.	`DrawerHandle<Payload>`	`—`
`modal`Determines if the drawer enters a modal state when open.	`boolean \| "trap-focus"`	`true`
`onOpenChangeComplete`Event handler called after any animations complete when the drawer is opened or closed.	`((open: boolean) => void)`	`—`
`snapToSequentialPoints`Disables velocity-based snap skipping so drag distance determines the next snap point.	`boolean`	`false`
`swipeDirection`The swipe direction used to dismiss the drawer.	`SwipeDirection`	`'down'`
`triggerId`ID of the trigger that the drawer is associated with.	`string \| null`	`—`
`children`The content of the drawer.	`React.ReactNode \| PayloadChildRenderFunction<Payload>`	`—`

SwipeArea`Drawer.SwipeArea`

An invisible area that listens for swipe gestures to open the drawer. Renders a <div>.

SwipeArea props
Prop	Type	Default
`swipeDirection`The swipe direction that opens the drawer.	`SwipeDirection`	`—`
`disabled`Whether the swipe area is disabled.	`boolean`	`false`

SwipeArea data attributes
Data attribute	Description
`data-open`	Present when the drawer is open.
`data-closed`	Present when the drawer is closed.
`data-disabled`	Present when the swipe area is disabled.
`data-swipe-direction`	Indicates the swipe direction.
`data-swiping`	Present when the drawer is being swiped.

Title`Drawer.Title`

A heading that labels the drawer. Renders a <h2>.

Trigger`Drawer.Trigger`

A button that opens the drawer. Renders a <button>.

Trigger props
Prop	Type	Default
`handle`A handle to associate the trigger with a drawer.	`DrawerHandle<Payload>`	`—`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`
`payload`A payload to pass to the drawer when it is opened.	`Payload`	`—`
`id`ID of the trigger.	`string`	`—`

Trigger data attributes
Data attribute	Description
`data-disabled`	Present when the trigger is disabled.
`data-popup-open`	Present when the corresponding dialog is open.

Viewport`Drawer.Viewport`

A positioning container for the drawer popup that can be made scrollable. Renders a <div>.

Viewport data attributes
Data attribute	Description
`data-open`	Present when the drawer is open.
`data-closed`	Present when the drawer is closed.
`data-starting-style`	Present when the drawer begins animating in.
`data-ending-style`	Present when the drawer is animating out.
`data-nested`	Present when the drawer is nested within another drawer.

Viewport CSS variables
CSS variable	Description
`--drawer-keyboard-inset`	The software keyboard inset, measured from the bottom edge of the layout viewport. Present only when the drawer is wrapped in `Drawer.VirtualKeyboardProvider`.

VirtualKeyboardProvider`Drawer.VirtualKeyboardProvider`

Provides keyboard-aware focus and scroll handling for bottom-sheet drawers with form fields.

VirtualKeyboardProvider props
Prop	Type	Default
`children`	`React.ReactNode`	`—`

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Drawer takes Dialog's keys: Escape closes it, and Tab stays inside the popup while it is modal.

Accessibility

What the parts set
Part	Sets	So that
Trigger	`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`	a screen reader says the button opens a dialog and whether it is open
Popup	`role="dialog"`, `aria-labelledby` to Title, `aria-describedby` to Description	the drawer is announced as a dialog with its heading and description
Popup	`aria-hidden="true"` on the rest of the page while `modal` is on	a screen reader stays inside the drawer
Backdrop	`role="presentation"`	the overlay is not read
SwipeArea	`role="presentation"`, `aria-hidden="true"`	the invisible gesture area is not read or reached

Focus order

Opening moves focus to Popup, or to initialFocus.
Tab and Shift+Tab stay inside the popup while it is modal; with modal off, focus can leave.
Closing returns focus to the Trigger that opened it, or to finalFocus.

Installation

Anatomy

Examples

Position

Nested

Snap Points

Virtual Keyboard Aware

Indent Provider

Non Modal

Swipe Area

API reference

BackdropDrawer.Backdrop

CloseDrawer.Close

ContentDrawer.Content

DescriptionDrawer.Description

IndentDrawer.Indent

IndentBackgroundDrawer.IndentBackground

PopupDrawer.Popup

PortalDrawer.Portal

ProviderDrawer.Provider

RootDrawer.Root

SwipeAreaDrawer.SwipeArea

TitleDrawer.Title

TriggerDrawer.Trigger

ViewportDrawer.Viewport

VirtualKeyboardProviderDrawer.VirtualKeyboardProvider