Popover

Popovers display related content or functionality that is related to a particular element.

Usage advice
Default
With title
With title & text button
Opened by an input
Implementation

Usage advice

Do	Don't
Use to provide additional information related to an element on the page.	Don't use for complex content on mobile. In this case, a modal may be a better bet.
Use when content is too long for a tooltip.	Don't use when you want content to be accessed on hover.
Use when the user needs to access additional functionality, without losing their current place in the UI.
Use when you want a contextual relationship with an element on screen that a modal or dialog can't provide.
Use for feature prompts / onboarding.
Popovers can be modal and shown on top of a scrim, especially for prompts.
When an element is pressed to open the popover, pressing on the same element should close it again (especially on desktop).

Default

With title

Popovers can be configured to have a title, this is displayed at the top opposite a close button.

With title & text button

As above, but with the close button displayed as text.

Opened by an input

You can use a BpkInput enhanced with the withOpenEvents higher-order component to open popovers.

Implementation

Backpack popover component.

Installation

npm install bpk-component-popover --save-dev

Usage

import React, { Component } from 'react';
import BpkButton from 'bpk-component-button';
import BpkPopover from 'bpk-component-popover';
import BpkText from 'bpk-component-text';

class App extends Component {
  constructor() {
    super();

    this.state = {
      isOpen: false,
    };

  }

  openPopover = () => {
    this.setState({
      isOpen: true,
    });
  }

  closePopover = () => {
    this.setState({
      isOpen: false,
    });
  }

  render() {
    return (
      <div id="popover-container">
        <BpkPopover
          id="my-popover"
          target={
            <BpkButton onClick={this.openPopover}>Open</BpkButton>
          }
          onClose={this.closePopover}
          isOpen={this.state.isOpen}
          label="My popover"
          closeButtonText="Close"
          renderTarget={() =>
            document.getElementById('popover-container')
          }
          closeButtonProps={{
            tabIndex: 0,
          }}
        >
          <BpkText>My popover content</BpkText>
        </BpkPopover>
      </div>
    );
  }
}

Theming: In order to theme the modal, a renderTarget needs to be supplied as a function which returns a DOM node in the scope of a BpkThemeProvider.

Props

Property	PropType	Required	Default Value
children	node	true	-
closeButtonText	string	true	-
id	string	true	-
isOpen	bool	true	-
label	string	true	-
onClose	func	true	-
target	element or func	true	-
closeButtonIcon	bool	false	true
closeButtonProps	object	false	null
labelAsTitle	bool	false	false
padded	bool	false	true
placement	oneOf(['top', 'right', 'bottom', 'left'])	false	'bottom'
popperModifiers	arrayOf(object)	false	null
portalClassName	string	false	null
portalStyle	object	false	null
renderTarget	func	false	null

In order to attach the popover to a regular DOM element, provide a function which returns it to target:

<BpkPopover
  id="my-popover"
  target={() => document.getElementById('mydiv')}
  onClose={this.closePopover}
  isOpen={this.state.isOpen}
  label="My popover"
  closeButtonText="Close"
>
  <BpkText>My popover content</BpkText>
</BpkPopover>

Prop Details

onClose

const onClose = (event, {
  source: <string>, // One of `DOCUMENT_CLICK`, `CLOSE_BUTTON`, `CLOSE_LINK`, `ESCAPE`
}) => {
  ...
}

popperModifiers

Please refer to the documentation for the underlying positioning library "Popper.js". You can achieve various behaviours such as allowing the popover to overflow the viewport etc.

Theme Props

linkColor
linkHoverColor
linkActiveColor
linkVisitedColor