View Source

Popover

A non-blocking container positioned to a specific anchor element.

A popover is a type of Dialog that is meant to provide additional context to content (an "anchor") currently on-screen. Typically, a popover is spawned by interacting with the content it enriches and is dismissed by clicking or shifting focus to an alternate location.

Alignment options for the popover are designed to mirror compass directions:

       →       ←
      NNW  N  NNE
↓ WNW             ENE ↓
    W   ANCHOR    E
↑ WSW             ESE ↑
      SSW  S  SSE
       →       ←

The arrows indicate which way the popover will extend, e.g. → means the popover is aligned to the left edge and extends in that direction. Diagonal corners (NW, NE, SE, SW) are currently not supported.

<Popover
    anchor={document.querySelector('.some-anchor-element')}
    preset={Popover.preset.N}>
    My popover content!
</Popover>

Installation#

npm i --save boundless-popover

Popover can also just be directly used from the main Boundless library. This is recommended when you're getting started to avoid maintaining the package versions of several components:

npm i boundless --save

the ES6 import statement then becomes like:

import { Popover } from 'boundless';

Demo

Words of the day for 11/25/2024:
Note that the words with ⓘ symbols have their caret anchored to the symbol, rather than the center of the button.

Show Implementation

Props#

Required Props#

NameImplementationDescription
anchor
Expects
HTMLElement or object
Default Value
undefined

a DOM element or React reference (ref) to one for positioning purposes

Optional Props#

NameImplementationDescription
*
Expects
any

any React-supported attribute

after
Expects
any renderable
Default Value
null

arbitrary content to be rendered after the dialog in the DOM

autoReposition
Expects
bool
Default Value
true

if the given alignment settings would take the popover out of bounds, change the alignment as necessary to remain in the viewport

before
Expects
any renderable
Default Value
null

arbitrary content to be rendered before the dialog in the DOM

captureFocus
Expects
bool
Default Value
true

determines if focus is allowed to move away from the dialog

caretAnchor
Expects
HTMLElement or object
Default Value
undefined

a DOM element or React reference (ref) to one for positioning purposes, the caret component will be automatically positioned to center on this provided anchor; by default it will center on props.anchor

caretComponent
Expects
ReactElement
Default Value
<svg viewBox='0 0 14 9.5' xmlns='http://www.w3.org/2000/svg'>
    <g>
        <polygon className='b-popover-caret-border' fill='#000' points='7 0 14 10 0 10' />
        <polygon className='b-popover-caret-fill' fill='#FFF' points='6.98230444 1.75 12.75 10 1.25 10' />
    </g>
</svg>

the JSX that is rendered and used to point at the middle of the anchor element and indicate the context of the popover

closeOnEscKey
Expects
bool or function
Default Value
false

enable detection of "Escape" keypresses to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

closeOnInsideClick
Expects
bool or function
Default Value
false

enable detection of clicks inside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

closeOnOutsideClick
Expects
bool or function
Default Value
false

enable detection of clicks outside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

closeOnOutsideFocus
Expects
bool or function
Default Value
false

enable detection of focus outside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

closeOnOutsideScroll
Expects
bool or function
Default Value
false

enable detection of scroll and mousewheel events outside the dialog area to trigger props.onClose; if a function is provided, the return value determines if the dialog will be closed

component
Expects
string
Default Value
'div'

override the type of .b-dialog-wrapper HTML element

dialogComponent
Expects
string
Default Value
'div'

override the type of .b-dialog HTML element

dialogProps
Expects
object
Default Value
{}
*
Expects
any

any React-supported attribute

onClose
Expects
function
Default Value
() => {}

a custom event handler that is called to indicate that the dialog should be unrendered by its parent; the event occurs if one or more of the "closeOn" props (closeOnEscKey, closeOnOutsideClick, etc.) are passed as true and the dismissal criteria are satisfied

portalProps
Expects
object
Default Value
{}
*
Expects
any

any React-supported attribute

children
Expects
any renderable
Default Value
null

any normal React child, but must be singular; multiple sibling children must have a common wrapper, such as a "layout" <div>

✅ OK:

<Portal>
  foo
</Portal>

<Portal>
  <div>foo</div>
</Portal>

<Portal>
  <div>
      <div>foo</div>
      <div>bar</div>
  </div>
</Portal>

⛔️ Not OK:

<Portal>
  <div>foo</div>
  <div>bar</div>
</Portal>
destination
Expects
HTMLElement
Default Value
document.body

the location to append the generated portal and child elements

portalId
Expects
string
Default Value
null

the ID used to link the portal origin to the destination; added to generated <div> appended to the destination HTML node

preset
Expects
Popover.preset.NNW or
Popover.preset.N or
Popover.preset.NNE or
Popover.preset.ENE or
Popover.preset.E or
Popover.preset.ESE or
Popover.preset.SSE or
Popover.preset.S or
Popover.preset.SSW or
Popover.preset.WSW or
Popover.preset.W or
Popover.preset.WNW
Default Value
Popover.preset.S

Example:

<Popover
    anchor={document.querySelector('.some-anchor-element')}
    preset={Popover.preset.NNE}>
    My popover content!
</Popover>