@paprika/popover

Description

Popover component renders an overlay of content anchored to a trigger button (or specific positioning element). It can be triggered by click (or keypress), by hover (or keyboard focus – as a tooltip), or programatically

Installation

yarn add @paprika/popover

or with npm:

npm install @paprika/popover

Props

Popover

| Prop | Type | required | default | Description | |-------|-------| -------- | --------- | ----------- | |align|[ Popover.types.align.TOP, Popover.types.align.RIGHT, Popover.types.align.BOTTOM, Popover.types.align.LEFT]|false|Popover.types.align.BOTTOM| Where the popover content is positioned relative to the trigger or getPositioningElement.| |children|node|true|-| Content of the popover| |isDark|bool|false|false| Displays as a "tooltip" style with white text on black background.| |isEager|bool|false|false| Activated by mouseOver / focus instead of onClick.| |isOpen|bool|false|null| How "controlled" popovers are shown / hidden.| |isPortal|bool|false|true| This renders the popover inline in the DOM and not in a react portal. WARNING: will have side effects with paprika side panels and modals, use with caution.| |defaultIsOpen|bool|false|null| How "uncontrolled" popovers can be rendered open by default.| |edge|[ Popover.types.align.LEFT, Popover.types.align.RIGHT, null]|false|null| Where the edge of the popover content is based on the trigger or getPositioningElement| |maxWidth|[string,number]|false|320| Maximum width of popover content. Using a number is recommended and implies px units.| |minWidth|[string,number]|false|0| Minimumn width of popover content. Using a number is recommended and implies px units.| |onClose|func|false|null| Callback to fire when user closes popover.| |offset|number|false|parseInt(tokens.spaceLg, 10)| Distance, in px, between popover content edge and trigger / getPositioningElement.| |getPositioningElement|func|false|null| Function that provides DOM element to use as target for positioning the popover.| |getScrollContainer|func|false|null| Function that provides the scrolling DOM element that contains the popover.| |shouldKeepFocus|bool|false|false| If focus will stay at the trigger when showing popover. Popover can still be closed when clicking outside or pressing escape key.| |shouldUnmount|bool|false|true| Should unmount Popover Content or Tip Subcomponents from DOM when popover is closed| |zIndex|number|false|zValue(1)| Number setting the z-index for the popover content / tip.| |container|custom|false|null| Portal container for the Panel (DOM element)|

Popover.Trigger

| Prop | Type | required | default | Description | |-------|-------| -------- | --------- | ----------- | |a11yText|string|false|null| Descriptive a11y text for assistive technologies for the trigger.| |children|[func,node]|true|-| |

Popover.Content

| Prop | Type | required | default | Description | |-------|-------| -------- | --------- | ----------- | |children|node|false|null| |

Popover.Card

| Prop | Type | required | default | Description | |-------|-------| -------- | --------- | ----------- | |children|node|true|-| |

Popover.Tip

| Prop | Type | required | default | Description | |-------|-------| -------- | --------- | ----------- | |zIndex|number|false|null| Number setting the z-index|

Usage

The <Popover> can be used as a controlled or uncontrolled component. If controlled, the isOpen and onClose props must be utilized.

Tooltip style

The <Popover> can be used as a tooltip by making it open "eagerly" on hover or keyboard focus via the isEager prop. Typically a very short tooltip is also designed with white text on a black background, achieved with the isDark prop.

Popover.Trigger

With an uncontrolled <Popover>, it may be convenient to use the <Popover.Trigger> to wrap the element the user will interact with to display the popover because this results in a <RawButton> being wrapped around that UI element, with all of the handlers it requires already hooked up.

For a controlled <Popover>, or the case where the <Popover.Trigger> child element is a <Button>, it is necessary to use a render function for the children of the <Popover.Trigger>, which will be provided with a generic handler argument.

It may not be necessary to use a <Popover.Trigger> element at all if the <Popover> is controlled. Then its children (excluding <Popover.Content> and <Popover.Tip>) will by default be used as the positioning element (see Basic controlled example below).

Popover.Content

Content for the <Popover> is also included as children, wrapped by the <Popover.Content>. For a "card" style, the <Popover.Card> is a convenient helper.

Popover.Tip

To include an arrow that points to the trigger element, the <Popover.Tip> can be included as a sibling element of the <Popover.Content> (include it after the Content to avoid an explicit zIndex prop on the Tip).

Basic uncontrolled example

import Popover from "@paprika/popover";

...

<Popover>
  <Popover.Trigger>
    <Icon />
  </Popover.Trigger>
  <Popover.Content>
    <Popover.Card>Lorem hipsum kombucha leggings vinyl.</Popover.Card>
  </Popover.Content>
  <Popover.Tip />
</Popover>

Uncontrolled example with button trigger

import Popover from "@paprika/popover";

...

<Popover>
  <Popover.Trigger>
    {(onClickHandler, a11yAttributes) => (
      <Button onClick={onClickHandler} {...a11yAttributes}>
        Open Popover
      </Button>
    )}
  </Popover.Trigger>
  <Popover.Content>
    <Popover.Card>Lorem hipsum kombucha leggings vinyl.</Popover.Card>
  </Popover.Content>
  <Popover.Tip />
</Popover>

Basic controlled example

import Popover from "@paprika/popover";

...

const [isOpen, setOpen] = React.useState(false);

...

<Popover isOpen={isOpen} onClose={() => { setOpen(false) }}>
  <Button onClick={() => { setOpen(true) }}>
    Open Popover
  </Button>
  <Popover.Content>
    <Popover.Card>Lorem hipsum kombucha leggings vinyl.</Popover.Card>
  </Popover.Content>
  <Popover.Tip />
</Popover>

Links

• Storybook Showcase
• GitHub source code
• Create GitHub issue
• CHANGELOG