Popover

Figma

Github

Storybook

Aria pattern Legacy component

Popovers are floating overlays that contain additional information or interactive content.

Importing

The components can be imported via:

import { 
	Popover, 
	PopoverTrigger, 
	PopoverTriggerButton,
	PopoverContent 
} from '@customerio/pluma-components/react';

Usage

A Popover is composed of several components:

PlumaPopover - the root component, which sets up the context, state and interactions
PlumaPopoverTrigger - the element that triggers the popover to show
PlumaPopoverTriggerButton - a Button component that acts as a trigger for the popover
PlumaPopoverContent - the content that will be shown when the trigger is clicked

Basic content

If the content of the popover is simple, header and description props accept strings to be rendered inside the popover:

<Popover 
	header="Example popover" 
	description="Example content"
>
	<PopoverTrigger>
		<Text>Click me</Text>
	</PopoverTrigger>
</Popover>

The popover "trigger" will render as an unstyled button tag, to make it focusable and visible to assistive technology.

When the popover is attached to text, the isUnderlined prop can be used on the trigger to add a bottom border to it, to draw more attention to it:

<Popover 
	header="Example popover" 
	description="Example content"
>
	<PopoverTrigger isUnderlined={true}>
		<Text>Click me</Text>
	</PopoverTrigger>
</Popover>

Placement

The component accepts a placement argument, which accepts one of these values:

type Placement =
	| 'top'
	| 'top-start'
	| 'top-end'
	| 'right'
	| 'right-start'
	| 'right-end'
	| 'bottom'
	| 'bottom-start'
	| 'bottom-end'
	| 'left'
	| 'left-start'
	| 'left-end';

For example:

<Box display="flex" gap="500">
	<Popover description="I am the popover content" placement="top">
		<PopoverTrigger>
			<Text>Click me</Text>
		</PopoverTrigger>
	</Popover>

	<Popover description="I am the popover content" placement="top-start">
		<PopoverTrigger>
			<Text>Click me</Text>
		</PopoverTrigger>
	</Popover>

	<Popover description="I am the popover content" placement="right">
		<PopoverTrigger>
			<Text>Click me</Text>
		</PopoverTrigger>
	</Popover>
</Box>

Usually, the contents of a popover will be more than a simple string. To render any custom content inside the popover, use the PopoverContent component, and do not use the description and header props:

<Popover>
	<PopoverTrigger>
		<Text>Click me</Text>
	</PopoverTrigger>

	<PopoverContent>
		<ButtonGroup>
			<Button>Button 1</Button>
			<Button>Button 2</Button>
			<Button>Button 3</Button>
		</ButtonGroup>
	</PopoverContent>
</Popover>

Focus trap

You'll notice that when the popover opens, the first focusable element inside it will receive focus. This is an accessibility feature.

In addition to moving focus into the popover, the popover can also "trap" focus, as recommended in the Dialog ARIA pattern. While popovers aren't usually as prominent as a Modal, they may have to be treated as such depending on use case.

Enabling the focus trap will ensure that focus stays within the popover: when tabbing through items in the popover, tabbing past the last item will move focus to the first item, and vice versa.

The focus trap can be enabled with the shouldTrapFocus prop:

<Popover shouldTrapFocus={true}>
	<PopoverTrigger>
		<Text>Click me</Text>
	</PopoverTrigger>

	<PopoverContent>
		<Paragraph mb="200">Try tabbing through these buttons:</Paragraph>

		<ButtonGroup>
			<Button>Button 1</Button>
			<Button>Button 2</Button>
			<Button>Button 3</Button>
		</ButtonGroup>
	</PopoverContent>
</Popover>

More focus trap options are available via the following props:

Custom trigger elements

By default, PopoverTrigger will render an unstyled button tag. It is important to render an element that is focusable, and that indicates it can be clicked.

If you'd like to use a different component as a trigger, PopoverTrigger is polymorphic, and accepts an as prop. When doing this, make sure the component or element you use is focusable and clickable.

<Popover 
	header="Example popover" 
	description="Example content"
>
	<PopoverTrigger as={Button} variant="primary">
		Click me
	</PopoverTrigger>
</Popover>

Using a button as trigger

The PopoverTriggerButton component is a convenient way to use a Button as the trigger for your popover. It supports all Button props (variant, size, icon, etc.).

<Popover 
	header="Example popover" 
	description="Example content"
>
	<PopoverTriggerButton variant="primary" icon="chevron-down" iconPosition="trailing">
		Click me
	</PopoverTriggerButton>
</Popover>

Custom trigger

Alternatively, the Popover component also exposes Floating UI props, which can be used to attach trigger interactions to any element.

This can be used by passing in a render function into the content, passing setReference into the component's ref, and spreading getReferenceProps:

Click me

<Popover>
	{(context) => (
		<Label
			color="green"
			ref={context.reference.setReference}
			{...context.reference.getReferenceProps()}
			role="button"
		>
			Click me
		</Label>
	)}

	<PopoverContent>
		<ButtonGroup>
			<Button>Button 1</Button>
			<Button>Button 2</Button>
			<Button>Button 3</Button>
		</ButtonGroup>
	</PopoverContent>
</Popover>

Custom trigger interactions

By default, the popover will open when the trigger is clicked. Popovers typically contain long form or interactive content, and as such require intent to open and close.

However, if you'd like to open the popover on hover, this can be enabled via shouldTriggerOnHover:

<Popover 
	header="Example popover" 
	description="Example content"
	shouldTriggerOnClick={false}
	shouldTriggerOnHover={true}
>
	<PopoverTrigger>
		<Text>Hover me</Text>
	</PopoverTrigger>
</Popover>

Custom middleware

In addition to the existing middlewareOptions prop for customizing the behavior of the tooltip, it's possible to provide entire custom middleware functions, which can be used for more complex scenarios or special use cases.

For example, we can create a middleware that changes the position of the tooltip's arrow:

import { Popover } from '@customerio/pluma-components/react';

const arrowMiddleware = {
	name: 'customArrowMiddleware',
	fn: (state) => {
		if (state.middlewareData?.arrow?.x != null) {
			state.middlewareData.arrow.x = 2;
		}

		return state;
	}
}

export default function Example() {
	return (
		<Popover 
			header="Example popover" 
			description="Example content"
			additionalMiddleware={[arrowMiddleware]}
		>
			<PopoverTrigger>
				<Text>Click me</Text>
			</PopoverTrigger>
		</Popover>
	);
}

API

`PlumaPopover`

`additionalMiddleware` `{ name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Promisable<MiddlewareReturn>; }[] | undefined`

Additional middleware to apply to Floating UI, for example custom middleware for more control. These will be applied after the default middleware.

`animationTransitionDuration` `number | undefined`

Default:125

The duration (in ms) for the popover animation.

`content` `string | undefined`

The text content to show in the popover. Deprecated: use description instead

`defaultIsOpen` `boolean | undefined`

Whether the popover should be open initially

`description` `string | undefined`

The text content to show in the popover

`floatingPluginOptions` { click?: { enabled?: boolean | undefined; event?: "click" | "mousedown" | undefined; toggle?: boolean | undefined; ignoreMouse?: boolean | undefined; keyboardHandlers?: boolean | undefined; } | undefined; hover?: { enabled?: boolean | undefined; mouseOnly?: boolean | undefined; delay?: number | Partial<{ open: number; close: number; }> | undefined; restMs?: number | undefined; move?: boolean | undefined; handleClose?: any; } | undefined; focus?: { enabled?: boolean | undefined; visibleOnly?: boolean | undefined; } | undefined; dismiss?: { enabled?: boolean | undefined; escapeKey?: boolean | undefined; referencePress?: boolean | undefined; referencePressEvent?: "click" | "mousedown" | "pointerdown" | undefined; outsidePress?: boolean | ((event: MouseEvent) => boolean) | undefined; outsidePressEvent?: "click" | "mousedown" | "pointerdown" | undefined; ancestorScroll?: boolean | undefined; bubbles?: boolean | { escapeKey?: boolean | undefined; outsidePress?: boolean | undefined; } | undefined; capture?: boolean | { escapeKey?: boolean | undefined; outsidePress?: boolean | undefined; } | undefined; } | undefined; role?: { enabled?: boolean | undefined; role?: "grid" | "listbox" | "menu" | "tooltip" | "dialog" | "label" | "select" | "tree" | "alertdialog" | "combobox" | undefined; } | undefined; } | undefined

Additional options to pass to Floating UI's plugins/hooks.

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

Default:['content']

The order in which focus should be moved when navigating through the popover. See Floating UI for more details.

`header` `string | undefined`

Header text to display in the popover

`initialFocus` `number | HTMLElement | undefined`

Default:0

Which element to initially focus when the popover is opened. Can be a number (a tabbable index as specified by focusOrder) or an HTMLElement. See Floating UI for more details.

`isDisabled` `boolean | undefined`

Default:false

Whether the popover should be disabled. Can be used to conditionally enable/disable a popover depending on state.

`isDraggable` `boolean | undefined`

Default:false

Whether the popover should be draggable.

`isFocusManagerDisabled` `boolean | undefined`

Default:false

Whether the focus manager (for the opened popover) should be disabled entirely. See Floating UI for more details.

`isOpen` `boolean | undefined`

Whether the popover should be open. Only use this along with onOpenChange if you want to control the state of the popover

`listNavigationOptions` `{ activeIndex?: number | null | undefined; onNavigate?: ((activeIndex: number | null) => void) | undefined; loop?: boolean | undefined; virtual?: boolean | undefined; allowEscape?: boolean | undefined; focusItemOnHover?: boolean | undefined; focusItemOnOpen?: boolean | undefined; } | undefined`

Additional options to pass to Floating UI's list navigation plugin.

`middlewareOptions` { arrow?: Partial<{ padding?: Padding | undefined; element: Element; }> | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Partial<{ padding?: Padding | undefined; element: Element; }>) | undefined; offset?: Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number | null; }> | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number | null; }>) | undefined; flip?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; fallbackPlacements?: Placement[] | undefined; fallbackStrategy?: "initialPlacement" | "bestFit" | undefined; fallbackAxisSideDirection?: "none" | "end" | "start" | undefined; flipAlignment?: boolean | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; fallbackPlacements?: Placement[] | undefined; fallbackStrategy?: "initialPlacement" | "bestFit" | undefined; fallbackAxisSideDirection?: "none" | "end" | "start" | undefined; flipAlignment?: boolean | undefined; boundary?: Boundary | undefined; }) | undefined; shift?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } | undefined; boundary?: Boundary | undefined; }) | undefined; hide?: { padding?: Padding | undefined; strategy?: "referenceHidden" | "escaped" | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; strategy?: "referenceHidden" | "escaped" | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; }) | undefined; size?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; apply?: ((args: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; } & { availableWidth: number; availableHeight: number; }) => Promisable<void>) | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; apply?: ((args: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; } & { availableWidth: number; availableHeight: number; }) => Promisable<void>) | undefined; }) | undefined; } | undefined

Additional options to pass into Floating UI middleware

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

Called when the open state of the popover is changing

`placement` `Placement | undefined`

Where the popover should be placed in relation to the trigger

`shouldCloseOnFocusOut` `boolean | undefined`

Default:true

Whether focusout event listeners are attached to the trigger and popover, to close the popover when focus moves outside of it. See Floating UI for more details.

`shouldNavigateList` `boolean | undefined`

Default:false

Whether the popover should navigate through a list of items when the arrow keys are pressed. See Floating UI for more details.

`shouldRenderFocusGuards` `boolean | undefined`

Default:true

Whether the focus guards are rendered by the focus manager. See Floating UI for more details.

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

Default:true

Whether the popover content's max width and/or max height should be restricted using the Floating UI size middleware.

By default, this is enabled, to prevent popovers from growing larger than the available viewport size.

Popover

animationTransitionDuration number | undefined

content string | undefined

defaultIsOpen boolean | undefined

description string | undefined

focusOrder ("content" | "reference" | "floating")[] | undefined

header string | undefined

initialFocus number | HTMLElement | undefined

isDisabled boolean | undefined

isDraggable boolean | undefined

isFocusManagerDisabled boolean | undefined

isOpen boolean | undefined

onOpenChange ((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined

placement Placement | undefined

shouldCloseOnFocusOut boolean | undefined

shouldNavigateList boolean | undefined

shouldRenderFocusGuards boolean | undefined

shouldRestrictSize boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined

shouldReturnFocus boolean | undefined

shouldShowVisuallyHiddenDismiss boolean | undefined

shouldTrapFocus boolean | undefined

shouldTriggerOnClick boolean | undefined

shouldTriggerOnFocus boolean | undefined

shouldTriggerOnHover boolean | undefined

strategy Strategy | undefined

unsafe_popoverClassName string | undefined

unsafe_popoverContentClassName string | undefined

unsafe_popoverStyle Record<string, unknown> | undefined

unsafe_registerNodeId ((id: string) => void) | undefined

withArrow boolean | undefined

withTypeahead boolean | undefined

isUnderlined boolean | undefined

PlumaPopoverTriggerButton extends Button

On this page

`animationTransitionDuration` `number | undefined`

`content` `string | undefined`

`defaultIsOpen` `boolean | undefined`

`description` `string | undefined`

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

`header` `string | undefined`

`initialFocus` `number | HTMLElement | undefined`

`isDisabled` `boolean | undefined`

`isDraggable` `boolean | undefined`

`isFocusManagerDisabled` `boolean | undefined`

`isOpen` `boolean | undefined`

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

`placement` `Placement | undefined`

`shouldCloseOnFocusOut` `boolean | undefined`

`shouldNavigateList` `boolean | undefined`

`shouldRenderFocusGuards` `boolean | undefined`

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

`shouldReturnFocus` `boolean | undefined`

`shouldShowVisuallyHiddenDismiss` `boolean | undefined`

`shouldTrapFocus` `boolean | undefined`

`shouldTriggerOnClick` `boolean | undefined`

`shouldTriggerOnFocus` `boolean | undefined`

`shouldTriggerOnHover` `boolean | undefined`

`strategy` `Strategy | undefined`

`unsafe_popoverClassName` `string | undefined`

`unsafe_popoverContentClassName` `string | undefined`

`unsafe_popoverStyle` `Record<string, unknown> | undefined`

`unsafe_registerNodeId` `((id: string) => void) | undefined`

`withArrow` `boolean | undefined`

`withTypeahead` `boolean | undefined`

`isUnderlined` `boolean | undefined`

`PlumaPopoverTriggerButton` `extends Button`