Popover

Default version

The default version of a popover acts like a tooltip, except that it shows up on click rather than on hover. A "tooltip" popover provides additional information, but cannot contain any interactive elements.

<FlexBox justifyContent="center" alignItems="center" pt={10}>
  <Popover>
    <PopoverLauncher>
      <TextButton>Launch a popover!</TextButton>
    </PopoverLauncher>
    <PopoverContent>Here is the content in the popover.</PopoverContent>
  </Popover>
</FlexBox>

<!-- the trigger can be any element, not just a button -->
<button class="textbutton" data-popover-target="my-example-popover">
  Launch a popover!
</button>
<template class="popover-content" data-popover="my-example-popover">
  Here is the content in the popover.
</template>

Dialog version

If the popover has any interactive elements, it's acting not as a tooltip, but rather as a (modeless) dialog, so it needs additional properties to provide proper accessibility support.

<FlexBox justifyContent="center" alignItems="center" pt={11}>
  <Popover>
    <PopoverLauncher>
      <TextButton>Launch a popover!</TextButton>
    </PopoverLauncher>
    <PopoverContent dialog>
      Here is the content for the dialog popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<!-- the trigger can be any element, not just a button -->
<button
  class="textbutton"
  data-popover-target="my-example-popover"
  data-popover-role="dialog"
>
  Launch a popover!
</button>
<template class="popover-content" data-popover="my-example-popover">
  Here is the content for the dialog popover.
  <!-- any element with class "popover-close" will close the popover -->
  <button class="popover-close">Close this popover</button>
</template>

"full-bleed"

The "full-bleed" option removes the padding around the popover's contents.

<FlexBox justifyContent="center" alignItems="center" pt={10}>
  <Popover>
    <PopoverLauncher>
      <TextButton>Launch a popover!</TextButton>
    </PopoverLauncher>
    <PopoverContent fullBleed>
      Here is the content in the popover.
    </PopoverContent>
  </Popover>
</FlexBox>

<!-- the trigger can be any element, not just a button -->
<button
  class="textbutton"
  data-popover-target="my-example-popover"
  data-popover-skin="full-bleed"
>
  Launch a popover!
</button>
<template class="popover-content" data-popover="my-example-popover">
  Here is the content in the popover.
</template>

Popover Inside Modal

When you want to override the container dom on which the events are listened for auto-closing of popovers

() => {
  const [isOpen, setIsOpen] = React.useState(false)
  const eventRef = React.createRef()

  return (
    <div>
      <TextButton onClick={() => setIsOpen(true)}>Open Modal</TextButton>
      <ModalDialog
        takeOver
        isOpen={isOpen}
        onRequestDismiss={() => setIsOpen(false)}
      >
        <ModalDialogContent aria-label="dialog content" ref={eventRef}>
          <ModalDialogBody>
            <Popover
              expanded
              position="right"
              my={11}
              eventContainerRef={eventRef}
            >
              <PopoverLauncher>
                <TextButton>Launch a popover!</TextButton>
              </PopoverLauncher>
              <PopoverContent>
                Here is the content in the popover.
              </PopoverContent>
            </Popover>
          </ModalDialogBody>
        </ModalDialogContent>
      </ModalDialog>
    </div>
  )
}

Components

Guidelines

Designer Guidelines

Do

• Use to show additional information at a contextual level.

• Keep content brief and small. Popovers have a maximum width of 375px.

Don't

• Expect to have precise control over the popover's position or the arrowhead's position.

• Remove the arrowhead that points to the element from which it launched.

• Place any critical information in a popover, since search engines can't see any information that requires user interaction to view.

Developer Guidelines

• If the popover contains any interactive elements, use a "dialog" popover.

• The trigger element must be accessible and clickable via keyboard. (The React PopoverLauncher defaults to a <button> tag, which meets this requirement.) If the triggering element is not normally keyboard-accessible, you will need to make it so; see "Keyboard Access" under Accessibility Utilities.

• Dialog popovers need an appropriate label for the dialog. If the popover has an internal heading, then the popover content element (PopoverContent in React, popover-content in vanilla) should have an attribute aria-labelledby whose value is the id of the heading. If the popover does not have a heading, then the popover content element needs an aria-label attribute whose value acts as a title for the dialog; the text for this value must be localized, since some browsers will read it to the user.

• The vanilla JS API uses a <template> tag for the content:

  • Content inside a <template> tag does not exist as an element in the DOM tree, so will not be available to JavaScript until the popover has been triggered. If you need the content to be available before the popover has been triggered, use an <aside> tag instead of a <template> tag.

  • If the <template> tag has an id, that id will not be passed on to the popover once created; the id stays associated with the <template>. Instead, if you need to give the popover a particular id, give the triggering element a data-popover-id attribute; its value will be added to the popover as its id.

SEO Considerations

• To be accessible to Googlebot, Popover content should be part of the page's source HTML on the server.

• Do not place important content that we want to rank inside a popover, since this content may be deprecated by search engine bots, as the content is semi-hidden.