@paprika/popover
v2.0.10
Published
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
Downloads
25,853
Keywords
Readme
@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>