Skip to main content

Popover

A popover allows the user to reveal more information or non-critical tasks in an overlay.

Anatomy

A popover with indicators calling out the corresponding anatomy items starting with popover container that contains, an arrow: pointing to an info icon, title: top left, close button icon: top right, body, and action buttons: bottom right.
  1. Container Container - the popover's container overlays the main page's content.
  2. Arrow - a visual indicator that points to the related element.
  3. Title (recommended) - the title of a callout summarizes its contents.
  4. Close Button (optional) - a button that will always close the popover.
  5. Body - the contents of the popover.
  6. Action Buttons (optional) - one or more custom actions that will result in the popover closing.

Usage

Use a popover for progressive disclosure of complex related information or actions that don't belong on the main page.

React API

We expose one component for the popover API, the Popover.

Popover

The Popover component extends the React.ComponentPropsWithoutRef<'div'> interface and uses Popper.js for positioning.

import { Popover } from '@wwnds/react';
Live Editor
function PopoverExample() {
	const [isOpen, setIsOpen] = React.useState(false);
	const [ref, setRef] = React.useState();

	return (
		<>
			<Button variant="solid" ref={setRef}>
				Show popover
			</Button>
			<Popover
				title="Title"
				hideTitle={false}
				hideCloseButton={false}
				placement="top"
				reference={ref}
				isOpen={isOpen}
				onRequestClose={() => setIsOpen(false)}
				onRequestOpen={() => setIsOpen(true)}
			>
				Lorem ipsum dolor sit amet, consectetur adipiscing elit,
				sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
				Ut enim ad minim veniam, quis nostrud exercitation ullamco
			</Popover>
		</>
	);
}
Result
Loading...
NameDescriptionType
title

The name of the Modal dialog. Required for accessibility but can be visually hidden with the hideTitle prop.

string
hideTitle

Indicates that the title should be visually hidden. It will still be accessible to screen reader users.

boolean
hideCloseButton

Indicates that the built-in close button in the top right should not be rendered.

boolean
actions

A list of actions or React Fragment that will be set inside an action bar at the bottom of the Modal dialog.

ReactElement<ButtonProps, string | JSXElementConstructor<any>>[] | ReactFragment
baseName
The base class name according to BEM conventions.string
headerClass
A className for the popover's header. Default will be ${baseName}__header.string
titleClass

A className for the popover's title, which goes inside the header. Default will be ${baseName}__title.

string
closeButtonClass

A className for the popover's close button, which goes inside the header. Default will be ${baseName}__close.

string
bodyClass

A className for the body of the popover, where the children go. Default will be ${baseName}__content.

string
actionBarClass
A className for the popover's action bar footer. Default will be ${baseName}__actionbar.string
arrowClass

A className for the popover's arrow. Default will be ${baseName}__arrow. @deprecated - Use arrowElement.

string
onOpen

Callback function that is called after the popover opens. The default function will focus the popover. Use this callback to focus something else inside the popover.

((popoverElement: HTMLElement) => void)
onClose

Callback function that is called after the popover closes. The default function will focus the reference element that opened the popover.

((shouldFocusReference: boolean) => void)
isOpen
Used to control whether the popper is open or closed.boolean
transition

The animation transition class applied to the popper as it enters or exits. A single name can be provided and it will be suffixed for each stage.

For example, transition="fade" applies:

  • fade-enter
  • fade-enter-active
  • fade-exit
  • fade-exit-active
  • fade-appear
  • fade-appear-active

Each individual stage can also be specified independently:

transition={{
    appear: 'my-appear',
    appearActive: 'my-appear-active',
    appearDone: 'my-appear-done',
    enter: 'my-enter',
    enterActive: 'my-enter-active',
    enterDone: 'my-enter-done',
    exit: 'my-exit',
    exitActive: 'my-exit-active',
    exitDone: 'my-exit-done'
}}

Reference: react-transition-group's CSSTransition.

string | CSSTransitionClassNames
reference

The reference element that the popper will be attached to.

Popper.js - createPopper

Element | VirtualElement | null
arrowElement

The element that should be used for the arrow.

See the arrow modifier's element option for more details.

string | HTMLElement | null
distance

The offset distance (in pixels) from the reference. Will only be used if offset is undefined.

number
boundary

The element or area where the popper will be checked against for overflow.

See the preventOverflow modifier's boundary option for more details.

Boundary
placement
The Popper.js placement option.Placement
modifiers
The Popper.js modifiers option.Partial<Modifier<any, any>>[]
strategy
The Popper.js strategy option.PositioningStrategy
onFirstUpdate
The Popper.js onFirstUpdate option.((arg0: Partial<State>) => void)
hideDelay

The duration in milliseconds that should elapse before closing, beginning after the pointer exits the reference's bounding box. Only has an effect for the mouseenter or pointerenter triggers.

number
showDelay

The duration in milliseconds that should elapse before opening, beginning after isOpen is set to true.

number
onRequestClose

A callback that occurs when the popper wants to close. The reason it is making this request is given by the first parameter.

  • "click.reference" - the reference element was clicked.
  • "click.internal" - something inside the popper was clicked.
  • "click.external" - something outside the popper or reference was clicked.
  • "escape" - the Escape key was pressed.
  • "blur" - the reference element lost focus. See blur event.
  • "pointerleave" - a pointer (mouse or touch) left the bounding box of the reference. See pointerenter event.
((triggeredBy: PopperTriggersClose) => void)
onRequestOpen

A callback that occurs when the popper wants to open. The reason it is making this request is given by the first parameter.

  • "click.reference" - the reference element was clicked.
  • "focus" - the reference was focused. See focus event.
  • "focusin" - the reference is about to be focused. See focusin event.
  • "pointerenter" - a pointer (mouse or touch) entered the bounding box of the reference. See pointerenter event.
((triggeredBy: PopperTriggersOpen) => void)