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.

Triggering a popover

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

Automatic trigger

Open popover

Manual trigger

Open popover

Code

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>
  );
}

Copy code Open in playground

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

Open popover

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>
  );
}

Copy code Open in playground

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.

Popover

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<Element | null>

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' .