Anatomy
Note: Image is not to scale
- Container
- Button icon
- Scrim
Options
Position
The drawer can be attached to any side of the screen.
Optional Close
The drawer close button icon can be optional.
Optional Scrim
The scrim is optional when using the drawer. Should note that without a scrim, it is recommended to have a close button to ensure users can close the drawer if that is desired.
Optional Scrim color
The scrim color can be changed by defining the color using one of our background colors from our tokens
Drawer color
The drawer color can be changed by defining the color using one of our background colors from our tokens.
Height and Width
Drawer width and height can be defined. Height can be defined if the position is top or bottom and width can be defined if the position is right or left.
Behavior
Closing
When the close button icon is rendered, the drawer can be closed by either clicking the scrim or the close button. Note: The drawer can be set to open and will remain open even if the scrim is clicked on.
Content overflow
Content will overflow, both vertically and horizontally, in the drawer by default.
Guidance
Content should be accessible
Do not combine colors of the drawer where text is not accessible to the user. Read more about WCAG accessible contrast requirements.
Avoid full screen
A drawer should never take the fullscreen of the viewer window. The drawer should always leave at least 1/3 of the screen available.
API Reference
DrawerRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| id | content id used for a11y | string | ---- | True |
| onOpenChange | callback to respond to open state | (boolean: any) => void | ---- | False |
| zIndex | Css z-index of drawer @default theme.zIndices.shell | ZIndex | Token<"shell", string, "zIndices", "wpds"> | 300 | False |
| open | controlled drawer open state, used with onOpenChange | boolean | ---- | False |
| defaultOpen | uncontrolled drawer open on mount | boolean | ---- | False |
DrawerContent
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| height | Height for a top or bottom positioned drawer @default 500 | number | "auto" | 500 | False |
| position | "bottom" | "left" | "right" | "top" | ({ "@reducedMotion"?: "bottom" | "left" | "right" | "top"; "@sm"?: "bottom" | "left" | "right" | "top"; "@md"?: "bottom" | "left" | "right" | "top"; ... 21 more ...; "@initial"?: "bottom" | ... 2 more ... | "top"; } & { ...; }) | bottom | False | |
| width | Width for a left or right positioned drawer @default 400 | number | "auto" | 400 | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| innerClassName | Additional class names for inner drawer element | string | ---- | False |
| loopFocus | When `true`, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tababble. @defaultValue true | boolean | true | False |
| trapFocus | When `true`, focus cannot escape the `Content` via keyboard, pointer, or a programmatic focus @defaultValue false | boolean | false | False |
DrawerTrigger
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| icon | "left" | "right" | "center" | "none" | ({ "@reducedMotion"?: "left" | "right" | "center" | "none"; "@sm"?: "left" | "right" | "center" | "none"; "@md"?: "left" | "right" | "center" | "none"; ... 21 more ...; "@initial"?: "left" | ... 2 more ... | "none"; } & { ...; }) | ---- | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
| variant | "cta" | "secondary" | "primary" | ({ "@reducedMotion"?: "cta" | "secondary" | "primary"; "@sm"?: "cta" | "secondary" | "primary"; "@md"?: "cta" | "secondary" | "primary"; "@lg"?: "cta" | "secondary" | "primary"; ... 20 more ...; "@initial"?: "cta" | ... 1 more ... | "primary"; } & { ...; }) | ---- | False | |
| density | "default" | "compact" | ({ "@reducedMotion"?: "default" | "compact"; "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; ... 19 more ...; "@initial"?: "default" | "compact"; } & { ...; }) | ---- | False | |
| isOutline | boolean | "true" | "false" | ({ "@reducedMotion"?: boolean | "true" | "false"; "@sm"?: boolean | "true" | "false"; "@md"?: boolean | "true" | "false"; "@lg"?: boolean | "true" | "false"; ... 20 more ...; "@initial"?: boolean | ... 1 more ... | "false"; } & { ...; }) | ---- | False |
DrawerClose
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| sticky | (boolean | "true" | ({ "@reducedMotion"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; ... 18 more ...; "@initial"?: boolean | "true"; } & { ...; })) & boolean | true | False | |
| icon | ("left" | "right" | "center" | "none" | ({ "@reducedMotion"?: "left" | "right" | "center" | "none"; "@sm"?: "left" | "right" | "center" | "none"; "@md"?: "left" | "right" | "center" | "none"; ... 21 more ...; "@initial"?: "left" | ... 2 more ... | "none"; } & { ...; })) & ("left" | ... 2 more ... | "none") | center | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
| variant | ("cta" | "secondary" | "primary" | ({ "@reducedMotion"?: "cta" | "secondary" | "primary"; "@sm"?: "cta" | "secondary" | "primary"; "@md"?: "cta" | "secondary" | "primary"; "@lg"?: "cta" | "secondary" | "primary"; ... 20 more ...; "@initial"?: "cta" | ... 1 more ... | "primary"; } & { ...; })) & ("cta" | ... 1 more .... | secondary | False | |
| density | ("default" | "compact" | ({ "@reducedMotion"?: "default" | "compact"; "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; ... 19 more ...; "@initial"?: "default" | "compact"; } & { ...; })) & ("default" | "compact") | compact | False | |
| isOutline | boolean | "true" | "false" | ({ "@reducedMotion"?: boolean | "true" | "false"; "@sm"?: boolean | "true" | "false"; "@md"?: boolean | "true" | "false"; "@lg"?: boolean | "true" | "false"; ... 20 more ...; "@initial"?: boolean | ... 1 more ... | "false"; } & { ...; }) | ---- | False |
DrawerCustomTrigger
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
| as | WPDS provides an as prop for changing which tag a component outputs. | string | ---- | False |
DrawerScrim
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| lockScroll | Whether scrollbars should be hidden and scroll locked when the scrim is shown @default true | boolean | ---- | False |