Popover API

Import

Cimpress UI exports two popover-related components:

PopoverRoot: component that connects a trigger button with its associated popover.
Popover: component that displays an overlay element positioned relative to a trigger.

import { Popover, PopoverRoot } from '@cimpress-ui/react';

Accessibility notes

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

Popovers can be closed by interacting outside or by pressing the Escape key.

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

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

It’s also possible to display a popover 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 popover’s open state manually.

Preview
Code

Automatic trigger

Manual trigger

import { Button, Popover, PopoverRoot, Stack, Text } from '@cimpress-ui/react';
import { useRef, useState } from 'react';

export default function Demo() {
  const [isOpen, setIsOpen] = useState(false);
  const triggerRef = useRef<HTMLButtonElement>(null);

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

        <PopoverRoot>
          <Button>Open popover</Button>
          <Popover title="Popover">This popover can be opened by an automatically attached trigger button.</Popover>
        </PopoverRoot>
      </Stack>

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

        <Button ref={triggerRef} onPress={() => setIsOpen(true)}>
          Open popover
        </Button>

        <Popover title="Popover" triggerRef={triggerRef} isOpen={isOpen} onOpenChange={setIsOpen}>
          This popover's open state is managed manually.
        </Popover>
      </Stack>
    </Stack>
  );
}

Closing programmatically

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

Preview
Code

import { Button, Popover, PopoverRoot, Stack, Text } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <PopoverRoot>
      <Button>Open popover</Button>
      <Popover title="Closing example">
        {({ close }) => (
          <Stack gap={16}>
            <Text as="p">Pressing the button below will close this popover.</Text>
            <Button onPress={close}>Close popover</Button>
          </Stack>
        )}
      </Popover>
    </PopoverRoot>
  );
}

API reference

PopoverRoot

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

PopoverRootProps

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

Displays an overlay element positioned relative to a trigger.

See popover usage guidelines.

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

PopoverProps

children * ReactNode | ((renderProps: PopoverRenderProps) => ReactNode): The contents of the popover. A function may be provided to access a function to close the popover.
title string: The title of the popover.
isOpen boolean: Whether the popover is open (controlled). If using PopoverRoot, this prop has no effect - provide isOpen to PopoverRoot instead.
defaultOpen boolean: Whether the popover is open by default (uncontrolled). If using PopoverRoot, this prop has no effect - provide defaultOpen to PopoverRoot instead.
onOpenChange (isOpen: boolean) => void: Handler that is called when the popover's open state changes. If using PopoverRoot, this prop has no effect - provide onOpenChange to PopoverRoot instead.
triggerRef RefObject<null | Element>: The ref for the element which the popover positions itself with respect to. When used within PopoverRoot, this is set automatically. Provide triggerRef only when Popover is used standalone.
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.
placement Placement: The placement of the element with respect to its anchor element.

Defaults to 'bottom' .