Drawer
fd-drawer is the reusable structural primitive for the global-header family’s mobile surfaces. In modal mode it now uses a native <dialog> shell, browser-managed backdrop, and native focus containment while keeping the close-request event and parent-owned open state contract.
When to use
- Use it when a drawer surface needs the same motion and close-request contract as the header family.
- Use it when the parent component should own state while the drawer owns the placed shell and translates native dialog dismissal into close requests.
- Use it for lightweight modal drawer surfaces, not for a full generic overlay system.
When not to use
- Don’t use it as a catch-all modal, popover, or toast primitive.
- Don’t use placement alone to decide semantics. Choose
modalwhen the drawer needs dialog behavior and focus containment; choose inline mode when the drawer belongs in the document flow.
Examples
Properties
| Name | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Whether the drawer is visible. |
label | string | `` | Accessible label announced for the drawer surface. |
modal | boolean | false | When true, the drawer uses a native modal <dialog> shell with a browser-managed backdrop and focus containment. |
placement | `"top" | "right" | "bottom" |
fd-drawerkeeps its public contract intentionally small so callers can compose navigation and search semantics around it.
Slots
| Name | Description |
|---|---|
header | Optional header content rendered above the body slot. |
Events
| Name | Detail | Description |
|---|---|---|
fd-drawer-close-request | { source: "backdrop" | "escape" } | Cancelable event fired when the user asks to dismiss the drawer. |
CSS custom properties
| Name | Default | Description |
|---|---|---|
--fd-drawer-surface | #ffffff | Surface color for the drawer body. |
--fd-drawer-color | inherit | Foreground color for drawer content. |
--fd-drawer-border-color | rgba(9, 53, 84, 0.14) | Border color for the drawer edge. |
--fd-drawer-shadow | 0 18px 48px rgba(0, 18, 32, 0.22) | Box shadow applied to the drawer surface. |
--fd-drawer-inline-size | 22rem | Inline size for left and right drawer placements. |
Shadow parts
| Name | Description |
|---|---|
base | Native dialog shell in modal mode, or the root wrapper in inline mode. |
surface | Drawer surface element inside the shell. |
header | Optional header slot wrapper. |
body | Drawer body wrapper. |
Accessibility
- When
modalis true, the drawer exposes native dialog semantics only while open and emitsfd-drawer-close-requestfor Escape and backdrop dismissal instead of closing itself. - Browser-native dialog behavior owns focus containment while the drawer is open. If a specific control should receive initial focus, author that control with
autofocus. - The parent component is still responsible for deciding whether a close request should actually close the surface and whether any explicit focus restoration beyond the native dialog default is needed.
- Drawer content stays semantic because the primitive only supplies the shell; callers provide links, buttons, headings, and landmarks.
Known limitations
- Drawer supports top, right, bottom, and left placement. Placement changes geometry and motion only; it does not change whether the drawer is modal or inline.
- Left and right placement attaches modal drawers to the viewport edge. Inline drawers stay in normal document flow, so placement only changes the drawer edge treatment and motion direction.
- Body scroll management and page inerting remain the caller’s responsibility.
- Modal backdrop styling now comes from the native dialog
::backdrop, so there is no separate backdrop shadow part to target.