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 { Drawer, DrawerActions, DrawerBody, 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. If you do this, you must provide a way for the user to close the drawer.

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

Automatic trigger

Open drawer

Manual trigger

Open drawer

Code

import { Button, Drawer, DrawerBody, 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>
  );
}

Copy code Open in playground

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

Open drawer

Code

import { Button, Drawer, DrawerActions, DrawerBody, 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>
  );
}

Copy code Open in playground

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.

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.

DrawerProps

children *

ReactNode | ((renderProps: 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 'small' .

isDismissible

boolean

Whether the drawer can be closed by clicking the close button, clicking outside of the drawer, or pressing the Escape key. When false, the drawer can only be closed programmatically.

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.

UNSTABLE_placement

'end' | 'start'

The placement of the drawer.

Defaults to 'end' .

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.

DrawerBodyProps

children *

ReactNode

The content to render within the drawer.

DrawerActions

Renders actions within Drawer.

DrawerActionsProps

children *

ReactNode

Actions that should be available in the drawer.