Popover

A Popover is a message box that is displayed floating over page content after pressing a trigger element, like an info-icon.

React

released

Vue

released

Elements

released

Android

unsupported

iOS

unsupported

Example

Example theme:

DBA lightFinn lightTori light

Usage

Design Guidelines

See Figma: Warp - Components / Popover

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #smp-warp-design-system

Frameworks

Import

You can import the component like so:

import { Attention } from '@warp-ds/react'

or import it individually to optimize your JS bundle size by adding only the components you need:

import { Attention } from '@warp-ds/react/components/attention'

Visual options

Default

function Example() {
  const [show, setShow] = React.useState(false)
  const targetEl = React.useRef()

  return (
    <div>
      <Button
        small
        aria-expanded={show}
        aria-controls='popover-attention-example'
        aria-details='popover-bubbletext'
        utility
        onClick={() => setShow(!show)}
        ref={targetEl}
      >
        Open menu
      </Button>
      <Attention
        popover
        placement='right'
        isShowing={show}
        flip={true}
        crossAxis={true}
        fallbackPlacements={['left', 'bottom', 'top']}
        targetEl={targetEl}
        id='popover-attention-example'
      >
        <ul id='popover-bubbletext'>
          <li>Hello</li>
          <li>World</li>
        </ul>
      </Attention>
    </div>
  )
}

With icon as target element

function PopoverIconAsTargetEl() {
  const [show, setShow] = React.useState(false)
  const containerRef = React.useRef<HTMLDivElement>(null)
  const targetEl = React.useRef<any>(null);

  React.useEffect(() => {
    function onBlurHandler(e) {
      if (containerRef.current && !containerRef.current.contains(e.target)) {
        setShow(false)
      }
    }
    document.addEventListener('mousedown', onBlurHandler)
    return () => {
      document.removeEventListener('mousedown', onBlurHandler)
    }
  })

  return (
  <div className='flex items-center justify-center'>
    <div ref={containerRef}>
      <Button
        small
        aria-expanded={show}
        aria-controls='popover-icon-target-el-attention-example'
        utility
        quiet
        onClick={() => setShow(!show)}
        className='w-max mb-0'
        ref={targetEl}
      >
        <IconInfo16 />
      </Button>
      <Attention
        popover
        placement='right-end'
        distance={-8}
        skidding={27}
        targetEl={targetEl}
        isShowing={show}
      >
        <ul className='bg-white w-full text-center'>
          <li
            tabIndex={0}
            className='p-2 px-40 hover:bg-blue-200 hover:text-blue-500 cursor-pointer'
          >
            Hello
          </li>
          <li
            tabIndex={0}
            className='p-2 px-40 hover:bg-blue-200 hover:text-blue-500 cursor-pointer'
          >
            World
          </li>
        </ul>
      </Attention>
    </div>
  </div>
  )
}

Flip prop

The attention component uses the Floating-ui library to calculate its position. By default, the flip prop is set to false, which means that the attention component will not flip its position to the opposite side.

Try to scroll up and down and see how the attention component doesn't move:

When flip is set to true, it will instead trigger Floating-ui's flip() function that will make sure that the attention component stays in viewport, by flipping it to the opposite side.

Try to scroll up and down and see how the attention component moves its position to the opposite side to keep itself in viewport as long as possible:

CrossAxis prop

The crossAxis prop decides whether to check for cross axis overflow or not when flip is set to true. By default, the crossAxis prop is set to false, which means that the attention component will ignore cross axis overflow.

Read more: Floating-ui crossAxis

FallbackPlacements prop

By default, fallbackPlacements is undefined. If flipis set to true, then you have the option to also use fallbackPlacements prop and pass in an array of preferred placements that you want the attention component to try if there is no longer any space left to position it to the initial placement, e.g. ['right', 'top'].

Read more: Floating-ui fallbackPlacements

Try to scroll up and down and see how the attention component's position starts at the bottom but then moves to the right and then to the top:

Accessibility

The attention component handles accessibility automatically by wrapping its slotted content with a div that has a default role attribute set to img when the popover prop is activated, and a default localized aria-label.

It is possible to remove the default role and override the aria-label attribute:

<Attention popover placement='right' isShowing={true} role='' aria-label=''>
  <p id='popover-bubbletext'>
    I'm a popover speech bubble with overridden role and aria-label attributes
    pointing up.
  </p>
</Attention>

If the user chooses to remove the role and/or override the aria-label attributes then it is important to also add aria-details on the target element.

Read more: MDN aria-details

Props

Required props

name	type	default	notes
targetEl	MutableRefObject		The reference container to which the Attention component is positioned relative to.

Optional Props

name	type	default	notes
isShowing	boolean	false	Whether Attention component is shown.
placement	'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end' | 'right-start' | 'right' | 'right-end'	'bottom'	Placement according to the target element. The arrow will point to the opposite side of this position
children	Element | Element[]		Elements inside of the Attention component
className	string		Extend the Attention component container styling
popover	boolean	false	Whether Attention component is rendered as a popover
role	string	img	Allows the user to remove the default ARIA role attribute for the Attention component, by supplying an empty role (role=""). Default role is set to img.
aria-label	string		Allows the user to override the default aria-label attribute for the Attention component
noArrow	boolean	false	Render Attention component without arrow
canClose	boolean	false	Whether a close button is shown
distance	number	8	Distance from which to offset the Attention component from the targetEl vertically
skidding	number	0	Distance from which to offset the Attention component along its targetEl horizontally.
flip	boolean	false	Whether Attention element should flip its placement in order to keep it in view
crossAxis	boolean	false	Whether Attention element should ignore cross axis overflow when flip is enabled. Can only be used when flip is set to true.
fallbackPlacements	array	undefined	Choose which preferred placements the Attention element should flip to. Can only be used when flip is set to true.

Events

name	when
onDismiss	() => void		Called when user clicks the close button or presses Escape when the button is in focus.