Overlays

A set of components for positioning beautiful overlays, tooltips, popovers, and anything else you need.

Overview

Things to know about the React-Boostrap Overlay components.

  • Overlays rely on the third-party library Popper.js. It's included automatically with React-Bootstrap, but you should reference the API for more advanced use cases.
  • The <Tooltip> and <Popover> components do not position themselves. Instead the <Overlay> (or <OverlayTrigger>) components, inject ref and style props.
  • Tooltip expects specific props injected by the <Overlay> component
  • Tooltips for disabled elements must be triggered on a wrapper element.

Overlay

Overlay is the fundamental component for positioning and controlling tooltip visibility. It's a wrapper around Popper.js, that adds support for transitions, and visibility toggling.

Creating an Overlay

Overlays consist of at least two elements, the "overlay", the element to be positioned, as well as a "target", the element the overlay is positioned in relation to. You can also also have an "arrow" element, like the tooltips and popovers, but that is optional. Be sure to check out the Popper documentation for more details about the injected props.

OverlayTrigger

Since the above pattern is pretty common, but verbose, we've included <OverlayTrigger> component to help with common use-cases. It even has functionality to delayed show or hides, and a few different "trigger" events you can mix and match.

Note that triggering components must be able to accept a ref since <OverlayTrigger> will attempt to add one. You can use forwardRef() for function components.

Customizing trigger behavior

For more advanced behaviors <OverlayTrigger> accepts a function child that passes in the injected ref and event handlers that correspond to the configured trigger prop.

You can manually apply the props to any element you want or split them up. The example below shows how to position the overlay to a different element than the one that triggers its visibility.

Tooltips

A tooltip component for a more stylish alternative to that anchor tag title attribute.

Examples

Hover over the links below to see tooltips.

You can pass the Overlay injected props directly to the Tooltip component.

Or pass a Tooltip element to OverlayTrigger instead.

Popovers

A popover component, like those found in iOS.

Examples

As with <Tooltip>s, you can control the placement of the Popover.

Disabled elements

Elements with the disabled attribute aren’t interactive, meaning users cannot hover or click them to trigger a popover (or tooltip). As a workaround, you’ll want to trigger the overlay from a wrapper <div> or <span> and override the pointer-events on the disabled element.

Changing containers

You can specify a container to control the DOM element the overlay is appended to. This is especially useful when styles conflict with your Overlay's.

Updating position dynamically

Since we can't know every time your overlay changes size, to reposition it, you need to take manual action if you want to update the position of an Overlay in response to a change.

For this, the Overlay component also injects a a popper prop with a scheduleUpdate() method that an overlay component can use to reposition itself.

API

Overlay

import Overlay from 'react-bootstrap/Overlay'Copy import code for the Overlay component
Name Type Default Description
children required
React.ReactElement<OverlayInjectedProps> | ((injected: OverlayInjectedProps) => React.ReactNode)
container
componentOrElement | function

A component instance, DOM node, or function that returns either. The container element will have the Overlay appended to it via a React portal.

onEnter
function

Callback fired before the Overlay transitions in

onEntered
function

Callback fired after the Overlay finishes transitioning in

onEntering
function

Callback fired as the Overlay begins to transition in

onExit
function

Callback fired right before the Overlay transitions out

onExited
function

Callback fired after the Overlay finishes transitioning out

onExiting
function

Callback fired as the Overlay begins to transition out

onHide
function

A callback invoked by the overlay when it wishes to be hidden. Required if rootClose is specified.

placement
'auto-start' | 'auto' | 'auto-end' | 'top-start' | 'top' | 'top-end' | 'right-start' | 'right' | 'right-end' | 'bottom-end' | 'bottom' | 'bottom-start' | 'left-end' | 'left' | 'left-start'
'top'

The placement of the Overlay in relation to it's target.

popperConfig
object
{}

A set of popper options and props passed directly to Popper.

rootClose
boolean
false

Specify whether the overlay should trigger onHide when the user clicks outside the overlay

rootCloseEvent
'click' | 'mousedown'

Specify event for triggering a "root close" toggle.

show
boolean
false

Set the visibility of the Overlay

target
componentOrElement | function

A component instance, DOM node, or function that returns either. The overlay will be positioned in relation to the target

transition
boolean | elementType
Fade

Animate the entering and exiting of the Overlay. true will use the <Fade> transition, or a custom react-transition-group <Transition> component can be provided.

OverlayTrigger

import OverlayTrigger from 'react-bootstrap/OverlayTrigger'Copy import code for the OverlayTrigger component
Name Type Default Description
children required
element | function
defaultShow
boolean
false

The initial visibility state of the Overlay.

delay
number | shape

A millisecond delay amount to show and hide the Overlay once triggered

flip
boolean
placement && placement.indexOf('auto') !== -1

The initial flip state of the Overlay.

onHide
null
onToggle
function
controls `show`

A callback that fires when the user triggers a change in tooltip visibility.

onToggle is called with the desired next show, and generally should be passed back to the show prop. onToggle fires after the configured delay

overlay required
function | element

An element or text to overlay next to the target.

placement
'auto-start' | 'auto' | 'auto-end' | 'top-start' | 'top' | 'top-end' | 'right-start' | 'right' | 'right-end' | 'bottom-end' | 'bottom' | 'bottom-start' | 'left-end' | 'left' | 'left-start'

The placement of the Overlay in relation to it's target.

popperConfig
object
{}

A Popper.js config object passed to the the underlying popper instance.

show
boolean
controlled by: onToggle, initial prop: defaultShow

The visibility of the Overlay. show is a controlled prop so should be paired with onToggle to avoid breaking user interactions.

Manually toggling show does not wait for delay to change the visibility.

target
null
trigger
'hover' | 'click' |'focus' | Array<'hover' | 'click' |'focus'>
['hover', 'focus']

Specify which action or actions trigger Overlay visibility

Tooltip

import Tooltip from 'react-bootstrap/Tooltip'Copy import code for the Tooltip component
Name Type Default Description
arrowProps
{ ref: ReactRef, style: Object }

An Overlay injected set of props for positioning the tooltip arrow.

This is generally provided by the Overlay component positioning the tooltip

id required
string|number

An html id attribute, necessary for accessibility

placement
'auto-start' | 'auto' | 'auto-end' | 'top-start' | 'top' | 'top-end' | 'right-start' | 'right' | 'right-end' | 'bottom-end' | 'bottom' | 'bottom-start' | 'left-end' | 'left' | 'left-start'
'right'

Sets the direction the Tooltip is positioned towards.

This is generally provided by the Overlay component positioning the tooltip

popper
object
show
any
bsPrefix
string
'tooltip'

Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

Popover

import Popover from 'react-bootstrap/Popover'Copy import code for the Popover component
Name Type Default Description
arrowProps
shape

An Overlay injected set of props for positioning the popover arrow.

This is generally provided by the Overlay component positioning the popover

content
boolean

When this prop is set, it creates a Popover with a Popover.Content inside passing the children directly to it

id required
string|number

An html id attribute, necessary for accessibility

placement
'auto' | 'top' | 'bottom' | 'left' | 'right'
'right'

Sets the direction the Popover is positioned towards.

This is generally provided by the Overlay component positioning the popover

popper
object
show
boolean
title
string
bsPrefix
string
'popover'

Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

PopoverContent

import PopoverContent from 'react-bootstrap/PopoverContent'Copy import code for the PopoverContent component
Name Type Default Description
as
elementType
<div>

Set a custom element for this component

bsPrefix
string
'popover-body'

Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

PopoverTitle

import PopoverTitle from 'react-bootstrap/PopoverTitle'Copy import code for the PopoverTitle component
Name Type Default Description
as
elementType
<div>

Set a custom element for this component

bsPrefix
string
'popover-header'

Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized bootstrap css.

© 2014–present Stephen J. Collings, Matthew Honnibal, Pieter Vanderwerff
Licensed under the MIT License (MIT).
https://react-bootstrap.github.io/components/overlays/