Skip to main content

Popover

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

Table of contents

Usage advice

DoDon'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

bpk-component-popover

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

PropertyPropTypeRequiredDefault Value
childrennodetrue-
closeButtonTextstringtrue-
idstringtrue-
isOpenbooltrue-
labelstringtrue-
onClosefunctrue-
targetelement or functrue-
closeButtonIconboolfalsetrue
closeButtonPropsobjectfalsenull
labelAsTitleboolfalsefalse
paddedboolfalsetrue
placementoneOf(['top', 'right', 'bottom', 'left'])false'bottom'
popperModifiersarrayOf(object)falsenull
portalClassNamestringfalsenull
portalStyleobjectfalsenull
renderTargetfuncfalsenull

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