Popover - Web

For development, import Popover from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Popover consists of three primary elements that work together to create floating containers that open on demand.

Popover background, content
Caret
Trigger

Options

The Popover supports the following configurations to accommodate various overlay scenarios.

Content

Popovers can accept both text and custom content.

Placement

Note that placement of a Popover will adjust when not enough space is available.

Behavior

The Popover responds to space constraints with automatic positioning adjustments and flexible opening/closing behaviors.

Positioning Adjustments

The Popover makes automatic adjustments to its placement and dimensions when space is limited. It will:

Auto flip when not enough space in the viewport is present.
Resize the Popover when not enough space is present.
Shift the Popover when scrolling to keep it in view.

These options can be turned off as needed. Popovers can be configured to open in multiple ways.

Open on click

Open on hover

Popovers can be configured to close in multiple ways.

Close on click outside

By default Popovers close on click outside. Override this behavior as needed. An action inside the Popover can close it. The Popover itself does not provide a set style for showing this.

Usage Guidelines

Standard	Requirement
DoCover use cases other components don’t	Popovers are small overlays that provide additional information or actions related to the element that triggers it. When a use case isn’t covered by other components, Popovers can be used to create a UI pattern that the design system has not yet established, such as a tour flow.
DoPosition to minimize obstruction	Position Popovers to minimize obstruction of important elements, auto-flipping to stay in view and defaulting to a top position; see Positioning a Popover.
Don’tUse Popover directly for common patterns	Popovers as a rule are not recommended to be used directly. The Menu and Combobox, both of which use Popover directly, cover most use cases for a Popover. Other overlay-type components, such as Tooltips and Dialogs, also cover use cases that a Popover could potentially use.
Don’tAdd Popovers to non-interactive elements	Popovers cannot be accessed by keyboard when behind a non-interactive element; see Don’t add Popovers to non-interactive elements.

Alternatives

When a user needs to selects from many options, the Combobox should be used over the Popover. It is not recommended to recreate a combobox-like or select-like interaction with a Popover. Both Dialogs and Popovers overlay elements on the page. In general, Dialogs are preferable when a situation requires user attention, and for more complicated flows.

	Popover	Dialog
Content allowed in the container?	Any content	Any content
Complexity of content?	From simple to a few interactions	From simple to high complex
Backdrop applied to page?	No	Yes

When a list of actions need to take place, the Menu should be used. It is not recommended to recreate menu-like interactions through a Popover. Tooltip is the component of choice for tips and other informational overlays. Popovers may be used in place of a Tooltip when actions are needed.

Usage	Tooltip	Popover
Can have a link?	Should not have interactive elements	Yes
Can have other interactive elements?	Should not have interactive elements	Yes
Open mechanic?	Hover or Focus	Click/Press, option for Hover or Focus
Can trap user focus?	No	Yes

How to Use

Popovers will auto flip and shift by default in order to stay in view. Define a starting position based on element placement: when elements are near a screen edge, position the Popover to open in the opposite direction.
Position Popovers in a way that minimizes obstruction of important elements.
If the above are not relevant, a top position is considered the default placement.

An example where the Popover position aligns with the position of a larger group of actions.

Don’t add Popovers to non-interactive elements

Popovers cannot be accessed by keyboard when behind a non-interactive element. Consider adding this information on the page itself, or providing a dedicated help Button Icon.

Don’t

Content

Content within the Popover should clearly communicate the additional information or actions available.

Keyboard Interaction

Users can navigate the Popover using standard keyboard controls.

Key	Description
Space or Enter	When focusing on the trigger, opens the Popover
Escape	Closes the Popover when focus is on or inside the trigger or the content
Tab	When the Popover is `modal`, it cycles through all tab-able elements between the trigger and Popover, otherwise it behaves normally

Accessibility

Trapping Focus

Popovers by default do not trap focus. Content of the Popover maintains the DOM order, unlike portaling, which allows natural tab behavior to work accessibly without trapping the focus. Enable focus trapping by using the modal prop. For more guidance on managing focus with changing content, see changing content best practices.

Code

Implementation
Popover Props
Popover.Button Props
Popover.Content Props
Popover.Trigger Props

Common Examples

import { Popover } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  return (
    <Popover>
      <Popover.Button>Click me!</Popover.Button>
      <Popover.Content>This is the popover content.</Popover.Content>
    </Popover>
  );
};

To build a popover, three components are required:

Popover: the configurable parent component
A way to control the open state of the popover. One of:
- Popover.Button: an Anvil2 Button
- Popover.Trigger: used to render a custom trigger component
Popover.Content: the content rendered within the popover

<Popover>
  <Popover.Button>Trigger Button</Popover.Button>
  <Popover.Content>Popover content. Accepts a ReactNode.</Popover.Content>
</Popover>

Use the placement prop on the Popover to change the default positioning. The popover will reposition itself if there is not enough space in the default placement.

<Popover placement="top">...</Popover>

Controlling popovers

Popovers can be controlled or uncontrolled (default). Control the popover using the open prop.

Uncontrolled (default)

Controlled

Using a custom trigger

To use something other than an Anvil2 Button to trigger the popover, use the Popover.Trigger component. The Popover.Trigger passes a set of props to the children that should be passed to an interactive HTML element, such as a button or input.

<Popover>
  <Popover.Trigger>
    {(props) => <button {...props}>Open Popover</button>}
  </Popover.Trigger>
  <Popover.Content>Content</Popover.Content>
</Popover>

The Popover.Close button can be used to close the popover from within the popover content.On controlled popovers, the onClick prop should be used to update the open state:

<Popover.Close onClick={() => setIsOpenState(false)} icon={Close} />

Disabling default closing behavior

By default, an uncontrolled popover closes if either the user clicks outside of the popover, or the user presses the “Escape” key. Both of these behaviors can be disabled with props:

Disable close on outside click

Disable close on “Escape” press

Enabling trapped focus

By default, the popover content does not trap focus so that users can navigate the content with a keyboard without naturally. To enable this behavior, set the modal prop of the Popover to true.

Default without trapping

Trapped focus

Using with Anvil1

Popover from version 1.23.0 uses HTML popover API which utilizes top-layer. This feature puts what’s inside the top-layer to be on the top of entire the HTML. Because of this, there are cases where it does not work well with Anvil1’s portaled components.

While having the Popover open, if a portaled Anvil1 component is triggered to open from within, the Popover will be on top always. This is something we can potentially adjust in Anvil1 and we have a spike ticket internally for it. If you encounter this issue, please reach out to us.
While having the Popover open, if a Drawer or Dialog from Anvil1 is triggered to open, not within the Popover, the Popover will be on top of the Drawer or Dialog.

React Accessibility

Most of the accessibility considerations for managing aria props and keyboard focus are handled internally. There are some things to keep in mind while working with popovers:

Always test keyboard navigation for interactive elements within popovers. The user should be able to easily access the elements in a logical order.
If the popover includes a form, be sure to follow accessible best practices for form building.
When building a custom trigger using Popover.Trigger, be sure to pass the props to an interactive element, as certain aria props are included to properly connect the trigger to the content.

For more guidance on creating accessible components, see building accessible custom components best practices.

<Popover
  defaultOpen={false}
  disableAutoUpdate={false}
  disableCaret={false}
  disableCloseOnEscape={false}
  disableCloseOnClickOutside={false}
  modal={true}
  noPadding={false}
  open={false}
  openOnHover={false}
  placement="bottom"
  onClose={() => {}}
  onClickOutside={() => {}}
  onOpenAnimationStart={() => {}}
  onOpenAnimationComplete={() => {}}
  onCloseAnimationStart={() => {}}
  onCloseAnimationComplete={() => {}}
>
  <Popover.Button>Trigger</Popover.Button>
  <Popover.Content>Content</Popover.Content>
</Popover>

ReactNode

Should include Popover.Button or Popover.Trigger and Popover.Content.

boolean

Controls the default open state on uncontrolled popovers.

boolean

Disables all focus management entirely. Useful to delay focus management until after a transition completes or some other conditional state.

boolean

Removes the caret between the trigger and content.

boolean

See Disabling default closing behavior

boolean

See Disabling default closing behavior

Traps focus within the popover content.

boolean

Removes padding from popover content.

() => void

Callback when clicking outside the popover.

() => void

Called when the popover is closed, except after mouse exits when openOnHover is true.

() => void

Callback when closing animation completes.

() => void

Callback when closing animation starts.

() => void

Callback when opening animation completes.

() => void

Callback when opening animation starts.

boolean

Use to control open state of the popover.

boolean

Opens the popover on hover over the trigger. In most cases, use a Tooltip instead.

default:"bottom"

<Popover.Button appearance="primary" size="medium" onClick={() => {}}>
  Trigger Button
</Popover.Button>

The Popover.Button component accepts any valid Anvil2 Button component props, with one difference — the children prop is required in Popover.Button.

<Popover.Trigger>
  {(data) => (
    <button {...data} aria-expanded={data["aria-expanded"]} onClick={data.onClick}>
      Custom Trigger
    </button>
  )}
</Popover.Trigger>

`Popover.Trigger` Props

(data) => ReactElement

The data parameter includes "aria-expanded", a ref for the trigger component, and some additional accessibility fields.

​Anatomy

​Options

​Content

​Placement

​Behavior

​Positioning Adjustments

​Opening a Popover

​Open on click

​Open on hover

​Closing a Popover

​Close on click outside

​Close action in the Popover

​Usage Guidelines

​Alternatives

​Popover vs Combobox

​Popover vs Dialog

​Popover vs Menu

​Popover vs Tooltip

​How to Use

​Positioning a Popover

​Don’t add Popovers to non-interactive elements

​Content

​Keyboard Interaction

​Accessibility

​Trapping Focus

​Code

​Common Examples

​Popover basics

​Popover placement

​Controlling popovers

​Uncontrolled (default)

​Controlled

​Using a custom trigger

​Popover close button

​Disabling default closing behavior

​Disable close on outside click

​Disable close on “Escape” press

​Enabling trapped focus

​Default without trapping

​Trapped focus

​Using with Anvil1

​React Accessibility

​Popover Props

​Popover.Button Props

​Popover.Content Props

​Popover.Trigger Props

Anatomy

Options

Content

Placement

Behavior

Positioning Adjustments

Opening a Popover

Open on click

Open on hover

Closing a Popover

Close on click outside

Close action in the Popover

Usage Guidelines

Alternatives

Popover vs Combobox

Popover vs Dialog

Popover vs Menu

Popover vs Tooltip

How to Use

Positioning a Popover

Don’t add Popovers to non-interactive elements

Content

Keyboard Interaction

Accessibility

Trapping Focus

Code

Common Examples

Popover basics

Popover placement

Controlling popovers

Uncontrolled (default)

Controlled

Using a custom trigger

Popover close button

Disabling default closing behavior

Disable close on outside click

Disable close on “Escape” press

Enabling trapped focus

Default without trapping

Trapped focus

Using with Anvil1

React Accessibility

`Popover` Props

`Popover.Button` Props

`Popover.Content` Props

`Popover.Trigger` Props