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 a 3rd party library react-popper, a tiny react wrapper around Popper.js. It's include 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 fundemental component for positioning and controlling tooltip visibility. It's a wrapper around react-popper, 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 react-popper documentation for more details about the injected props.
class Example extends React.Component { constructor(...args) { super(...args); this.attachRef = target => this.setState({ target }); this.state = { show: false, }; } render() { const { show, target } = this.state; return ( <> <Button variant="danger" ref={this.attachRef} onClick={() => this.setState({ show: !show })} > Click me to see </Button> <Overlay target={target} show={show} placement="right"> {({ placement, scheduleUpdate, arrowProps, ...props }) => ( <div {...props} style={{ backgroundColor: 'rgba(255, 100, 100, 0.85)', padding: '2px 10px', color: 'white', borderRadius: 3, ...props.style, }} > Simple tooltip </div> )} </Overlay> </> ); } } render(<Example />);
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 stateless function components.
const renderTooltip = props => ( <div {...props} style={{ backgroundColor: 'rgba(0, 0, 0, 0.85)', padding: '2px 10px', color: 'white', borderRadius: 3, ...props.style, }} > Simple tooltip </div> ); const Example = () => ( <OverlayTrigger placement="right-start" delay={{ show: 250, hide: 400 }} overlay={renderTooltip} > <Button variant="success">Hover me to see</Button> </OverlayTrigger> ); render(<Example />);
Tooltips
A tooltip component for a more stylish alternative to that anchor tag title
attribute.
Examples
Hover over the links below to see tooltips.
Tight pants next level keffiyeh you probably haven't heard of them. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel have a terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan whatever keytar, scenester farm-to-table banksy Austin twitter handle freegan cred raw denim single-origin coffee viral.
You can pass the Overlay
injected props directly to the Tooltip component.
class Example extends React.Component { constructor(...args) { super(...args); this.attachRef = target => this.setState({ target }); this.state = { show: false }; } render() { const { show, target } = this.state; return ( <> <Button ref={this.attachRef} onClick={() => this.setState({ show: !show })} > Click me! </Button> <Overlay target={target} show={show} placement="right"> {props => ( <Tooltip id="overlay-example" {...props}> My Tooltip </Tooltip> )} </Overlay> </> ); } } render(<Example />);
Or pass a Tooltip element to OverlayTrigger
instead.
<ButtonToolbar> {['top', 'right', 'bottom', 'left'].map(placement => ( <OverlayTrigger key={placement} placement={placement} overlay={ <Tooltip id={`tooltip-${placement}`}> Tooltip on <strong>{placement}</strong>. </Tooltip> } > <Button variant="secondary">Tooltip on {placement}</Button> </OverlayTrigger> ))} </ButtonToolbar>;
Popovers
A popover component, like those found in iOS.
Examples
const popover = ( <Popover id="popover-basic" title="Popover right"> And here's some <strong>amazing</strong> content. It's very engaging. right? </Popover> ); const Example = () => ( <OverlayTrigger trigger="click" placement="right" overlay={popover}> <Button variant="success">Click me to see</Button> </OverlayTrigger> ); render(<Example />);
As with <Tooltip>
s, you can control the placement of the Popover.
<ButtonToolbar> {['top', 'right', 'bottom', 'left'].map(placement => ( <OverlayTrigger trigger="click" key={placement} placement={placement} overlay={ <Popover id={`popover-positioned-${placement}`} title={`Popover ${placement}`} > <strong>Holy guacamole!</strong> Check this info. </Popover> } > <Button variant="secondary">Popover on {placement}</Button> </OverlayTrigger> ))} </ButtonToolbar>;
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.
<OverlayTrigger overlay={<Tooltip id="tooltip-disabled">Tooltip!</Tooltip>}> <span className="d-inline-block"> <Button disabled style={{ pointerEvents: 'none' }}> Disabled button </Button> </span> </OverlayTrigger>;
Changing containers
Yopu 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.
class Example extends React.Component { constructor(props, context) { super(props, context); this.handleClick = ({ target }) => { this.setState(s => ({ target, show: !s.show })); }; this.state = { show: false, }; } render() { return ( <ButtonToolbar> <Button onClick={this.handleClick}>Holy guacamole!</Button> <Overlay show={this.state.show} target={this.state.target} placement="bottom" container={this} containerPadding={20} > <Popover id="popover-contained" title="Popover bottom"> <strong>Holy guacamole!</strong> Check this info. </Popover> </Overlay> </ButtonToolbar> ); } } render(<Example />);
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 scheduleUpdate()
method that an overlay component can use to reposition itself.
class UpdatingPopover extends React.Component { componentDidUpdate(prevProps) { if (prevProps.children !== this.props.children) { console.log('updating!'); this.props.scheduleUpdate(); } } render() { return <Popover {...this.props} />; } } const longContent = ` Very long Multiline content that is engaging and what-not `; const shortContent = 'Short and sweet!'; class Example extends React.Component { constructor(props, context) { super(props, context); this.state = { content: shortContent }; } componentDidMount() { this.timer = setInterval(() => { this.setState(state => ({ content: state.content === shortContent ? longContent : shortContent, })); }, 3000); } render() { const { content } = this.state; return ( <OverlayTrigger trigger="click" overlay={ <UpdatingPopover id="popover-contained">{content}</UpdatingPopover> } > <Button onClick={this.handleClick}>Holy guacamole!</Button> </OverlayTrigger> ); } } render(<Example />);
API
Overlayview source file
import Overlay from 'react-bootstrap/Overlay'
Name | 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 react-popper's Popper component. | |
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 Ovelay. |
OverlayTriggerview source file
import OverlayTrigger from 'react-bootstrap/OverlayTrigger'
Name | Type | Default | Description |
---|---|---|---|
children required | element | ||
defaultShow | boolean | The initial visibility state of the Overlay. For more nuanced visibility control, consider using the Overlay component directly. | |
delay | number | shape | A millisecond delay amount to show and hide the Overlay once triggered | |
overlay | function | element | An element or text to overlay next to the target. | |
trigger | 'hover' | 'click' |'focus' | Array<'hover' | 'click' |'focus'> | ['hover', 'focus'] | Specify which action or actions trigger Overlay visibility |
Tooltipview source file
import Tooltip from 'react-bootstrap/Tooltip'
Name | Type | Default | Description |
---|---|---|---|
arrowProps | { ref: ReactRef, style: Object } | An Overlay injected set of props for positioning the tooltip arrow.
| |
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.
|
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'
Name | Type | Default | Description |
---|---|---|---|
arrowProps | shape | An Overlay injected set of props for positioning the popover arrow.
| |
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 Popover is positioned towards.
|
title | node | Title content | |
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. |