Overlays
A set of components for positioning beautiful overlays, tooltips, popovers, and anything else you need.
Overview
Things to know about the React-Bootstrap 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, injectref
andstyle
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.
Customizing Overlay rendering
The Overlay
injects a number of props that you can use to customize the
rendering behavior. There is a case where you would need to show the overlay
before Popper
can measure and position it properly. In React-Bootstrap,
tooltips and popovers sets the opacity and position to avoid issues where
the initial positioning of the overlay is incorrect. See the
Tooltip
implementation for an example on how this is done.
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 Overlays.
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
Overlayview source file
import Overlay from 'react-bootstrap/Overlay'
Copy import code for the Overlay componentName | Type | Default | Description |
---|---|---|---|
container | componentOrElement | function | A component instance, DOM node, or function that returns either.
The | |
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
| |
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 |
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 | |
transition | boolean | elementType | Fade | Animate the entering and exiting of the Overlay. |
OverlayTriggerview source file
import OverlayTrigger from 'react-bootstrap/OverlayTrigger'
Copy import code for the OverlayTrigger componentName | 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.
| |
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 | |
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. Manually toggling | |
target | null | ||
trigger | 'hover' | 'click' |'focus' | Array<'hover' | 'click' |'focus'> | ['hover', 'focus'] | Specify which action or actions trigger Overlay visibility The |
Tooltipview source file
import Tooltip from 'react-bootstrap/Tooltip'
Copy import code for the Tooltip componentName | Type | Default | Description |
---|---|---|---|
arrowProps | { ref: ReactRef, style: Object } | An Overlay injected set of props for positioning the tooltip arrow.
| |
hasDoneInitialMeasure | boolean | Whether or not Popper has done its initial measurement and positioning. | |
id required | string | 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.
|
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. |
Popoverview source file
import Popover from 'react-bootstrap/Popover'
Copy import code for the Popover componentName | Type | Default | Description |
---|---|---|---|
arrowProps | shape | An Overlay injected set of props for positioning the popover arrow.
| |
body | boolean | When this prop is set, it creates a Popover with a Popover.Body inside passing the children directly to it | |
hasDoneInitialMeasure | boolean | Whether or not Popper has done its initial measurement and positioning. | |
id required | string | 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 Popover is positioned towards.
|
popper | object | ||
show | boolean | ||
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. |
PopoverBodyview source file
import PopoverBody from 'react-bootstrap/PopoverBody'
Copy import code for the PopoverBody componentName | Type | Default | Description |
---|---|---|---|
as | elementType | <div> | You can use a custom element type for this component. |
bsPrefix required | 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. |
PopoverHeaderview source file
import PopoverHeader from 'react-bootstrap/PopoverHeader'
Copy import code for the PopoverHeader componentName | Type | Default | Description |
---|---|---|---|
as | elementType | <div> | You can use a custom element type for this component. |
bsPrefix required | 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. |