Popover

Introduction

Popovers display floating content next to a target element. Popover supports controlled and uncontrolled usage through isOpen and defaultIsOpen, respectively. Use onInteraction in controlled mode to respond to changes in the isOpen state.

Supported user interactions are dictated by the interactionKind prop.

Examples

Usage

Popover

import React from "react";
import { Popover, Position, PopoverInteractionKind } from "@commure/components-foundation";
function MyPopover() {
const popoverContent = <div>Whatever you want inside the popover window</div>
const popoverButton = <Button>Target</Button>
return (
<Popover
content={popoverContent}
target={popoverButton}
/>
);
}
export default MyPopover;

API Reference

When creating a popover, you must specify both its content and its target.

The target acts as the trigger for the popover; user interaction will show the popover based on interactionKind. The content will be shown in the popover itself. The popover's will always be positioned on the page next to the target; the position prop determines the relative position (on which side of the target).

The position prop controls the Popover's position relative to the target. The Position enumeration defines the full set of supported values. There are two attributes of positioning to consider:

  • Which side of the target the popover should render on.
  • The popover's alignment relative to the target.

Position enumeration:

  • BOTTOM_LEFT
  • BOTTOM
  • BOTTOM_RIGHT
  • LEFT_TOP
  • LEFT
  • LEFT_BOTTOM
  • TOP_LEFT
  • TOP
  • TOP_RIGHT
  • RIGHT_TOP
  • RIGHT
  • RIGHT_BOTTOM

The interactionKind prop governs how the popover should open and close in response to user interactions.

PopoverInteractionKind enumeration:

  • HOVER
  • HOVER_TARGET_ONLY
  • CLICK
  • CLICK_TARGET_ONLY

Popover

Prop NameRequired?TypeDescription
autoFocusfalsebooleanWhether the overlay should acquire application focus when it first opens.
backdropPropsfalseHTMLProps<HTMLDivElement>HTML props for the backdrop element. Can be combined with `backdropClassName`.
boundaryfalsePopperBoundaryDetermines the boundary element used by Popper for its `flip` and `preventOverflow` modifiers. Three shorthand keywords are supported; Popper will find the correct DOM element itself.
canEscapeKeyClosefalsebooleanWhether pressing the `esc` key should invoke `onClose`.
captureDismissfalsebooleanWhen enabled, `preventDefault()` is invoked on `click` events that close this popover, which will prevent those clicks from closing outer popovers. When disabled, clicking inside a `Classes.POPOVER_DISMISS` element will close the parent popover. See http://blueprintjs.com/docs/#core/components/popover.closing-on-click
classNamefalsestringA space-delimited list of class names to pass along to a child element.
contentfalsestring | ElementThe content displayed inside the popover. This can instead be provided as the _second_ element in `children` (first is `target`).
defaultIsOpenfalsebooleanInitial opened state when uncontrolled.
disabledfalsebooleanPrevents the popover from appearing when `true`.
enforceFocusfalsebooleanWhether the overlay should prevent focus from leaving itself. That is, if the user attempts to focus an element outside the overlay and this prop is enabled, then the overlay will immediately bring focus back to itself. If you are nesting overlay components, either disable this prop on the "outermost" overlays or mark the nested ones `usePortal={false}`.
hasBackdropfalsebooleanEnables an invisible overlay beneath the popover that captures clicks and prevents interaction with the rest of the document until the popover is closed. This prop is only available when `interactionKind` is `PopoverInteractionKind.CLICK`. When popovers with backdrop are opened, they become focused.
hoverCloseDelayfalsenumberThe amount of time in milliseconds the popover should remain open after the user hovers off the trigger. The timer is canceled if the user mouses over the target before it expires.
hoverOpenDelayfalsenumberThe amount of time in milliseconds the popover should wait before opening after the user hovers over the trigger. The timer is canceled if the user mouses away from the target before it expires.
inheritDarkThemefalsebooleanWhether a popover that uses a `Portal` should automatically inherit the dark theme from its parent.
interactionKindfalsePopoverInteractionKindThe kind of interaction that triggers the display of the popover.
isOpenfalsebooleanWhether the popover is visible. Passing this prop puts the popover in controlled mode, where the only way to change visibility is by updating this property. If `disabled={true}`, this prop will be ignored, and the popover will remain closed.
lazyfalsebooleanIf `true` and `usePortal={true}`, the `Portal` containing the children is created and attached to the DOM when the overlay is opened for the first time; otherwise this happens when the component mounts. Lazy mounting provides noticeable performance improvements if you have lots of overlays at once, such as on each row of a table.
minimalfalsebooleanWhether to apply minimal styles to this popover, which includes removing the arrow and adding `Classes.MINIMAL` to minimize and accelerate the transitions.
modifiersfalsePopperModifiersPopper modifier options, passed directly to internal Popper instance. See https://popper.js.org/popper-documentation.html#modifiers for complete details.
onClosefalse(event?: SyntheticEvent<HTMLElement>) => voidA callback that is invoked when user interaction causes the overlay to close, such as clicking on the overlay or pressing the `esc` key (if enabled). Receives the event from the user's interaction, if there was an event (generally either a mouse or key event). Note that, since this component is controlled by the `isOpen` prop, it will not actually close itself until that prop becomes `false`.
onClosedfalse(node: HTMLElement) => voidLifecycle method invoked just after the CSS _close_ transition ends but before the child has been removed from the DOM. Receives the DOM element of the child being closed.
onClosingfalse(node: HTMLElement) => voidLifecycle method invoked just before the CSS _close_ transition begins on a child. Receives the DOM element of the child being closed.
onInteractionfalse(nextOpenState: boolean, e?: SyntheticEvent<HTMLElement>) => voidCallback invoked in controlled mode when the popover open state *would* change due to user interaction.
onOpenedfalse(node: HTMLElement) => voidLifecycle method invoked just after the CSS _open_ transition ends. Receives the DOM element of the child being opened.
onOpeningfalse(node: HTMLElement) => voidLifecycle method invoked just after mounting the child in the DOM but just before the CSS _open_ transition begins. Receives the DOM element of the child being opened.
openOnTargetFocusfalsebooleanWhether the popover should open when its target is focused. If `true`, target will render with `tabindex="0"` to make it focusable via keyboard navigation.
popoverClassNamefalsestringA space-delimited string of class names applied to the popover element.
popoverReffalse(ref: HTMLDivElement | null) => voidRef supplied to the `Classes.POPOVER` element.
portalClassNamefalsestringSpace-delimited string of class names applied to the `Portal` element if `usePortal={true}`.
portalContainerfalseHTMLElementThe container element into which the overlay renders its contents, when `usePortal` is `true`. This prop is ignored if `usePortal` is `false`.
positionfalsePopoverPositionThe position (relative to the target) at which the popover should appear. The default value of `"auto"` will choose the best position when opened and will allow the popover to reposition itself to remain onscreen as the user scrolls around.
targetfalsestring | ElementThe target to which the popover content is attached. This can instead be provided as the _first_ element in `children`.
targetClassNamefalsestringSpace-delimited string of class names applied to the target element.
targetPropsfalseHTMLAttributes<HTMLElement>HTML props to spread to target element. Use `targetTagName` to change the type of element rendered. Note that `ref` is not supported.
targetTagNamefalsekeyof IntrinsicElementsHTML tag name for the target element. This must be an HTML element to ensure that it supports the necessary DOM event handlers. By default, a `<span>` tag is used so popovers appear as inline-block elements and can be nested in text. Use `<div>` tag for a block element.
transitionDurationfalsenumberIndicates how long (in milliseconds) the overlay's enter/leave transition takes. This is used by React `CSSTransition` to know when a transition completes and must match the duration of the animation in CSS. Only set this prop if you override Blueprint's default transitions with new transitions of a different length.
usePortalfalsebooleanWhether the popover should be rendered inside a `Portal` attached to `portalContainer` prop. Rendering content inside a `Portal` allows the popover content to escape the physical bounds of its parent while still being positioned correctly relative to its target. Using a `Portal` is necessary if any ancestor of the target hides overflow or uses very complex positioning. Not using a `Portal` can result in smoother performance when scrolling and allows the popover content to inherit CSS styles from surrounding elements, but it remains subject to the overflow bounds of its ancestors.
wrapperTagNamefalsekeyof IntrinsicElementsHTML tag name for the wrapper element, which also receives the `className` prop.

Related Reading

Blueprint Popover Reference
Blueprint Popover Position
Blueprint Popover Interaction Kind