Drawer

The drawer component creates a flexible overlay panel that provides focused workspace for forms, detailed views, or supplementary information.

import {Drawer} from "@qualcomm-ui/react/drawer"

Overview

The drawer's API is similar to the Dialog component.

Examples

Placement End

The drawer's default placement is end, which maps to the right side of the screen in LTR languages and the left side in RTL languages.

import type {ReactElement} from "react"

import {Button} from "@qualcomm-ui/react/button"
import {Drawer} from "@qualcomm-ui/react/drawer"
import {LoremIpsum} from "@qualcomm-ui/react-core/lorem-ipsum"

export function DrawerPlacementDemo(): ReactElement {
  return (
    <Drawer.Root>
      <Drawer.Trigger>
        <Button emphasis="primary" variant="fill">
          Open Drawer
        </Button>
      </Drawer.Trigger>
      <Drawer.FloatingPortal>
        <Drawer.Body>
          <Drawer.Heading>Drawer Title</Drawer.Heading>
          <Drawer.CloseButton />
          <Drawer.Description>
            <LoremIpsum />
          </Drawer.Description>
        </Drawer.Body>

        <Drawer.Footer>
          <Drawer.CloseTrigger>
            <Button emphasis="primary" size="sm" variant="fill">
              Confirm
            </Button>
          </Drawer.CloseTrigger>
        </Drawer.Footer>
      </Drawer.FloatingPortal>
    </Drawer.Root>
  )
}

Placement Start

Use placement start to change the placement to the left side of the screen.

<Drawer.Root placement="start">

Controlled State

Drawer visibility can be controlled using the open, onOpenChange and defaultOpen props. These props follow our controlled state pattern.

import {type ReactElement, useState} from "react"

import {Button} from "@qualcomm-ui/react/button"
import {Drawer} from "@qualcomm-ui/react/drawer"
import {LoremIpsum} from "@qualcomm-ui/react-core/lorem-ipsum"

export function DrawerControlledStateDemo(): ReactElement {
  const [open, setOpen] = useState<boolean>(false)

  return (
    <Drawer.Root onOpenChange={setOpen} open={open}>
      <Drawer.Trigger>
        <Button emphasis="primary" variant="fill">
          Open Drawer
        </Button>
      </Drawer.Trigger>
      <Drawer.FloatingPortal>
        <Drawer.Body>
          <Drawer.Heading>Drawer Title</Drawer.Heading>
          <Drawer.CloseButton />
          <Drawer.Description>
            <LoremIpsum />
          </Drawer.Description>
        </Drawer.Body>

        <Drawer.Footer>
          <Drawer.CloseTrigger>
            <Button emphasis="primary" size="sm" variant="fill">
              Confirm
            </Button>
          </Drawer.CloseTrigger>
        </Drawer.Footer>
      </Drawer.FloatingPortal>
    </Drawer.Root>
  )
}

Custom Container

Use the container prop of the Portal component to render the drawer in a custom container. You'll need to override the positioner's default styles to position the drawer correctly.

Consider setting closeOnInteractOutside to false to prevent the drawer from closing when interacting outside the drawer.

import {type ReactElement, useRef} from "react"

import {Button} from "@qualcomm-ui/react/button"
import {Drawer} from "@qualcomm-ui/react/drawer"
import {Portal} from "@qualcomm-ui/react-core/portal"

export function DrawerCustomContainerDemo(): ReactElement {
  const containerRef = useRef<HTMLDivElement | null>(null)

  return (
    <div className="grid gap-4">
      <Drawer.Root
        closeOnEscape={false}
        closeOnInteractOutside={false}
        preventScroll={false}
        trapFocus={false}
      >
        <div
          ref={containerRef}
          className="border-neutral-03 relative box-border flex h-96 w-[600px] overflow-hidden border p-8"
        >
          <Drawer.Trigger>
            <Button emphasis="primary" variant="fill">
              Open Drawer
            </Button>
          </Drawer.Trigger>
        </div>

        <Portal container={containerRef}>
          <Drawer.Positioner className="absolute z-0 h-full w-full">
            <Drawer.Content>
              <Drawer.Body>
                <Drawer.Heading>Title</Drawer.Heading>
                <Drawer.CloseButton />
                <Drawer.Description>Description</Drawer.Description>
              </Drawer.Body>

              <Drawer.Footer>
                <Drawer.CloseTrigger>
                  <Button emphasis="primary" size="sm" variant="fill">
                    Confirm
                  </Button>
                </Drawer.CloseTrigger>
              </Drawer.Footer>
            </Drawer.Content>
          </Drawer.Positioner>
        </Portal>
      </Drawer.Root>
    </div>
  )
}

Shortcuts

<Drawer.FloatingPortal>

A helper component that combines the portal, positioner, and content components. This shortcut is equivalent to:

<Portal {...props}>
  <Drawer.Backdrop {...backdropProps} />
  <Drawer.Positioner {...positionerProps}>
    <Drawer.Content {...contentProps}>{children}</Drawer.Content>
  </Drawer.Positioner>
</Portal>

API

The Drawer shares many of its props and data attributes with the Dialog component.

<Drawer.Root>

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

Prop	Type	Default
children ^* React children prop.	ReactNode
aria-label Human readable label for the dialog, used when the dialog title is not rendered	string
closeOnEscape Whether to close the dialog when the escape key is pressed	boolean	true
closeOnInteractOutside Whether to close the dialog when the outside is clicked	boolean	true
defaultOpen The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.	boolean	false
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
finalFocusEl Element to receive focus when the dialog is closed	() => HTMLElement
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
immediate Whether to synchronize the present change immediately or defer it to the next frame	boolean
initialFocusEl Element to receive focus when the dialog is opened	() => HTMLElement
lazyMount When true, the component will not be rendered in the DOM until it becomes visible or active.	boolean	false
modal Whether to prevent pointer interaction outside the element and hide all content below it	boolean	true
onEscapeKeyDown Function called when the escape key is pressed	( event: KeyboardEvent, ) => void
onExitComplete Function called when the animation ends in the closed state	VoidFunction
onFocusOutside Function called when the focus is moved outside the component	( event: FocusOutsideEvent, ) => void
onInteractOutside Function called when an interaction happens outside the component	( event: InteractOutsideEvent, ) => void
onOpenChange Function invoked when the dialog opens or closes open:The next value of the open state.	( open: boolean, ) => void
onPointerDownOutside Function called when the pointer is pressed down outside the component	( event: PointerDownOutsideEvent, ) => void
onRequestDismiss Function called when this layer is closed due to a parent layer being closed	( event: CustomEvent<{ originalIndex: number originalLayer: HTMLElement targetIndex: number targetLayer: HTMLElement }>, ) => void
open The controlled open state of the dialog	boolean
persistentElements Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event	Array< () => Element >
placement The horizontal placement of the drawer within the viewport.	\| 'start' \| 'end'	'end'
present Whether the node is present (controlled by the user)	boolean
preventScroll Whether to prevent scrolling behind the dialog when it's opened	boolean	true
restoreFocus Whether to restore focus to the element that had focus before the dialog was opened	boolean	true
role The dialog's role	\| 'dialog' \| 'alertdialog'	'dialog'
scrollBehavior Defines the scroll behavior of the dialog content when modal content exceeds viewport height. `'inside'`: The modal and backdrop create an internal scroll area within the modal. `'outside'`: The modal and backdrop move with the page scroll instead of creating an internal scroll area within the modal.	\| 'inside' \| 'outside'	'outside'
size The size of the drawer's width, font sizes, and internal spacing.	'sm' \| 'md'	'sm'
skipAnimationOnMount Whether to allow the initial presence animation.	boolean	false
trapFocus Whether to trap focus inside the dialog when it's opened	boolean	true
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false

children

Type

ReactNode

Description

React children prop.

aria-label

Type

string

Description

Human readable label for the dialog, used when the dialog title is not rendered

closeOnEscape

Type

boolean

Description

Whether to close the dialog when the escape key is pressed

closeOnInteractOutside

Type

boolean

Description

Whether to close the dialog when the outside is clicked

defaultOpen

Type

boolean

Description

The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

finalFocusEl

Type

() => HTMLElement

Description

Element to receive focus when the dialog is closed

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.

immediate

Type

boolean

Description

Whether to synchronize the present change immediately or defer it to the next frame

initialFocusEl

Type

() => HTMLElement

Description

Element to receive focus when the dialog is opened

lazyMount

Type

boolean

Description

When true, the component will not be rendered in the DOM until it becomes visible or active.

modal

Type

boolean

Description

Whether to prevent pointer interaction outside the element and hide all content below it

onEscapeKeyDown

Type

(
  event: KeyboardEvent,
) => void

Description

Function called when the escape key is pressed

onExitComplete

Type

VoidFunction

Description

Function called when the animation ends in the closed state

onFocusOutside

Type

(
  event: FocusOutsideEvent,
) => void

Description

Function called when the focus is moved outside the component

onInteractOutside

Type

(
  event: InteractOutsideEvent,
) => void

Description

Function called when an interaction happens outside the component

onOpenChange

Type

(
  open: boolean,
) => void

Description

Function invoked when the dialog opens or closes

open:The next value of the open state.

onPointerDownOutside

Type

(
  event: PointerDownOutsideEvent,
) => void

Description

Function called when the pointer is pressed down outside the component

onRequestDismiss

Type

(
  event: CustomEvent<{
    originalIndex: number
    originalLayer: HTMLElement
    targetIndex: number
    targetLayer: HTMLElement
  }>,
) => void

Description

Function called when this layer is closed due to a parent layer being closed

open

Type

boolean

Description

The controlled open state of the dialog

persistentElements

Type

Array<
  () => Element
>

Description

Returns the persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event

placement

Type

| 'start'
| 'end'

Description

The horizontal placement of the drawer within the viewport.

present

Type

boolean

Description

Whether the node is present (controlled by the user)

preventScroll

Type

boolean

Description

Whether to prevent scrolling behind the dialog when it's opened

restoreFocus

Type

boolean

Description

Whether to restore focus to the element that had focus before the dialog was opened

role

Type

| 'dialog'
| 'alertdialog'

Description

The dialog's role

scrollBehavior

Type

| 'inside'
| 'outside'

Description

Defines the scroll behavior of the dialog content when modal content exceeds viewport height.

'inside': The modal and backdrop create an internal scroll area within the modal.
'outside': The modal and backdrop move with the page scroll instead of creating an internal scroll area within the modal.

size

Type

'sm' | 'md'

Description

The size of the drawer's width, font sizes, and internal spacing.

skipAnimationOnMount

Type

boolean

Description

Whether to allow the initial presence animation.

trapFocus

Type

boolean

Description

Whether to trap focus inside the dialog when it's opened

unmountOnExit

Type

boolean

Description

When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.

<Drawer.Backdrop>

An overlay displayed beneath the drawer to prevent interaction with the rest of the page. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-dialog__backdrop'
`data-dialog-part`	'backdrop'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean

className

Value

'qui-dialog__backdrop'

data-dialog-part

Value

'backdrop'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

<Drawer.Positioner>

A container that positions the drawer on the screen. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-drawer__positioner'
`data-dialog-part`	'positioner'
`data-placement`	\| 'start' \| 'end'
`style`	CSSProperties

className

Value

'qui-drawer__positioner'

data-dialog-part

Value

'positioner'

data-placement

Value

| 'start'
| 'end'

style

Value

CSSProperties

<Drawer.Content>

A container for the drawer contents. Renders a <section> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-drawer__content'
`data-dialog-part`	'content'
`data-placement`	\| 'start' \| 'end'
`data-size`	'sm' \| 'md'
`data-state`	\| 'open' \| 'closed'
`hidden`	boolean
`tabIndex`	-1

className

Value

'qui-drawer__content'

data-dialog-part

Value

'content'

data-placement

Value

| 'start'
| 'end'

data-size

Value

'sm' | 'md'

data-state

Value

| 'open'
| 'closed'

hidden

Value

boolean

tabIndex

Value

-1

<Drawer.Body>

The main content of the drawer. Container for the heading, description, indicator, and primary content of the dialog. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-dialog__body'
`data-dialog-part`	'body'
`data-size`	'sm' \| 'md'

<Drawer.Heading>

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-dialog__heading'
`data-dialog-part`	'heading'
`data-size`	'sm' \| 'md'

<Drawer.IndicatorIcon>

Renders an icon that indicates the drawer's status. Renders a <span> element by default.

Prop	Type
icon Lucide-react icon or React Element. If this prop is omitted, a fallback icon will be rendered based on the emphasis prop.	\| LucideIcon \| ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

icon

Type

| LucideIcon
| ReactNode

Description

Lucide-react icon or React Element. If this prop is omitted, a fallback icon will be rendered based on the emphasis prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-dialog__indicator-icon'
`data-emphasis`	\| 'info' \| 'success' \| 'warning' \| 'danger' \| 'neutral'
`data-size`	'sm' \| 'md'

className

Value

'qui-dialog__indicator-icon'

data-emphasis

Value

| 'info'
| 'success'
| 'warning'
| 'danger'
| 'neutral'

data-size

Value

'sm' | 'md'

<Drawer.CloseButton>

A button that closes the drawer. Renders a <button> element by default.

Prop	Type	Default
icon	LucideIcon	X
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

icon

Type

LucideIcon

Description

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-dialog__close-button'
`data-dialog-part`	'close-trigger'

Last updated on Apr 24, 2026 by Ryan Bower

Divider

File Input