Drawer API

Import

Cimpress UI exports four drawer-related components:

DrawerRoot: component that connects a trigger button with its associated drawer.
Drawer: component that displays an overlay element which blocks interaction with outside elements.
DrawerBody: component that contains the main content of the drawer.
DrawerActions: component that contains the actions of the drawer.

import { UNSTABLE_Drawer, UNSTABLE_DrawerActions, UNSTABLE_DrawerBody, UNSTABLE_DrawerRoot } from '@cimpress-ui/react';

Accessibility notes

While a drawer is open, all content outside of it is hidden from assistive technologies.

By default, drawers can be closed by interacting outside or by pressing the Escape key. This can be disabled by setting the isDismissible prop to false. Regardless of the isDismissible value, the drawer can always be closed using the close button in the drawer header.

If your drawer contains form fields, we recommend to automatically focus one of the fields when the drawer is opened. This can be achieved by setting the autoFocus prop on the field that you want focused.

Drawer requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Triggering a drawer

To open a drawer when a trigger button is pressed, wrap both the trigger button and the drawer component with a DrawerRoot component. This will automatically associate the button with the drawer, without any manual setup.

It’s also possible to display a drawer programmatically (not as a result of a user action), or render it in a different part of the component tree than its trigger. In this case, you’ll have to manage the drawer’s open state manually.

Preview
Code

Automatic trigger

Manual trigger

import {
  Button,
  UNSTABLE_Drawer as Drawer,
  UNSTABLE_DrawerBody as DrawerBody,
  UNSTABLE_DrawerRoot as DrawerRoot,
  Stack,
  Text,
} from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Automatic trigger
        </Text>

        <DrawerRoot>
          <Button>Open drawer</Button>
          <Drawer title="Drawer">
            <DrawerBody>This drawer can be opened by an automatically attached trigger button.</DrawerBody>
          </Drawer>
        </DrawerRoot>
      </Stack>

      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Manual trigger
        </Text>

        <Button onPress={() => setIsOpen(true)}>Open drawer</Button>

        <Drawer title="Drawer" isOpen={isOpen} onOpenChange={setIsOpen}>
          <DrawerBody>This drawer's open state is managed manually.</DrawerBody>
        </Drawer>
      </Stack>
    </Stack>
  );
}

Closing programmatically

Drawers can be closed programmatically by passing a function as children to the Drawer component, and using the close function provided as an argument to that function.

Preview
Code

import {
  Button,
  UNSTABLE_Drawer as Drawer,
  UNSTABLE_DrawerActions as DrawerActions,
  UNSTABLE_DrawerBody as DrawerBody,
  UNSTABLE_DrawerRoot as DrawerRoot,
} from '@cimpress-ui/react';

export default function Demo() {
  return (
    <DrawerRoot>
      <Button>Open drawer</Button>
      <Drawer title="Closing example">
        {({ close }) => (
          <>
            <DrawerBody>Pressing the button below will close this drawer.</DrawerBody>
            <DrawerActions>
              <Button onPress={close}>Close drawer</Button>
            </DrawerActions>
          </>
        )}
      </Drawer>
    </DrawerRoot>
  );
}

API reference

DrawerRoot

Encapsulates a drawer trigger and its associated drawer. The trigger can be any Cimpress UI button, and the drawer will be displayed when the trigger is activated.

UNSTABLE_DrawerRootProps

children * ReactNode: The drawer trigger with its associated drawer. Provide the trigger as the first child, and the drawer as the second child.
isOpen boolean: Whether the drawer is open (controlled).
defaultOpen boolean: Whether the drawer is open by default (uncontrolled).
onOpenChange (isOpen: boolean) => void: Handler that is called when the drawer's open state changes.

Drawer

Displays an overlay element which blocks interaction with outside elements.

See drawer usage guidelines.

ref Ref<HTMLElement>: The ref type for this component.

UNSTABLE_DrawerProps

children * ReactNode | ((renderProps: UNSTABLE_DrawerRenderProps) => ReactNode): The contents of the drawer. A function may be provided to access a function to close the drawer.
title string: The title of the drawer.
size 'small' | 'medium' | 'large': The size of the drawer. This prop is ignored on small devices - drawers on small devices will always take up all available width.

Defaults to 'medium' .
isDismissible boolean: Whether to close the drawer when the user interacts outside of it or presses the Escape key.

Defaults to true .
isOpen boolean: Whether the drawer is open (controlled). If using DrawerRoot, this prop has no effect - provide isOpen to DrawerRoot instead.
defaultOpen boolean: Whether the drawer is open by default (uncontrolled). If using DrawerRoot, this prop has no effect - provide defaultOpen to DrawerRoot instead.
onOpenChange (isOpen: boolean) => void: Handler that is called when the drawer's open state changes. If using DrawerRoot, this prop has no effect - provide onOpenChange to DrawerRoot instead.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label string: Defines a string value that labels the current element.
aria-labelledby string: Identifies the element (or elements) that labels the current element.
aria-describedby string: Identifies the element (or elements) that describes the object.
aria-details string: Identifies the element (or elements) that provide a detailed, extended description for the object.

DrawerBody

Renders content within Drawer.

UNSTABLE_DrawerBodyProps

children * ReactNode: The content to render within the drawer.

DrawerActions

Renders actions within Drawer.

UNSTABLE_DrawerActionsProps

children * ReactNode: Actions that should be available in the drawer.