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.

function Example() {
  const [show, setShow] = useState(false);
  const target = useRef(null);

  return (
    <>
      <Button variant="danger" ref={target} onClick={() => setShow(!show)}>
        Click me to see
      </Button>
      <Overlay target={target.current} show={show} placement="right">
        {({ placement, arrowProps, show: _show, popper, ...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 />);

function Example() {
  const [show, setShow] = useState(false);
  const target = useRef(null);
  return (
    <>
      <Button variant="danger" ref={target} onClick={() => setShow(!show)}>
        Click me to see
      </Button>
      <Overlay target={target.current} show={show} placement="right">
        {({ placement, arrowProps, show: _show, popper, ...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 function components.

const renderTooltip = (props) => (
  <Tooltip id="button-tooltip" {...props}>
    Simple tooltip
  </Tooltip>
);

render(
  <OverlayTrigger
    placement="right"
    delay={{ show: 250, hide: 400 }}
    overlay={renderTooltip}
  >
    <Button variant="success">Hover me to see</Button>
  </OverlayTrigger>,
);

const renderTooltip = (props) => (
  <Tooltip id="button-tooltip" {...props}>
    Simple tooltip
  </Tooltip>
);
render(
  <OverlayTrigger
    placement="right"
    delay={{ show: 250, hide: 400 }}
    overlay={renderTooltip}
  >
    <Button variant="success">Hover me to see</Button>
  </OverlayTrigger>,
);

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.

render(
  <OverlayTrigger
    placement="bottom"
    overlay={<Tooltip id="button-tooltip-2">Check out this avatar</Tooltip>}
  >
    {({ ref, ...triggerHandler }) => (
      <Button
        variant="light"
        {...triggerHandler}
        className="d-inline-flex align-items-center"
      >
        <Image
          ref={ref}
          roundedCircle
          src="holder.js/20x20?text=J&bg=28a745&fg=FFF"
        />
        <span className="ms-1">Hover to see</span>
      </Button>
    )}
  </OverlayTrigger>,
);

render(
  <OverlayTrigger
    placement="bottom"
    overlay={<Tooltip id="button-tooltip-2">Check out this avatar</Tooltip>}
  >
    {({ ref, ...triggerHandler }) => (
      <Button
        variant="light"
        {...triggerHandler}
        className="d-inline-flex align-items-center"
      >
        <Image
          ref={ref}
          roundedCircle
          src="holder.js/20x20?text=J&bg=28a745&fg=FFF"
        />
        <span className="ms-1">Hover to see</span>
      </Button>
    )}
  </OverlayTrigger>,
);

Tooltips

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

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.

function Example() {
  const [show, setShow] = useState(false);
  const target = useRef(null);

  return (
    <>
      <Button ref={target} onClick={() => setShow(!show)}>
        Click me!
      </Button>
      <Overlay target={target.current} show={show} placement="right">
        {(props) => (
          <Tooltip id="overlay-example" {...props}>
            My Tooltip
          </Tooltip>
        )}
      </Overlay>
    </>
  );
}

render(<Example />);

function Example() {
  const [show, setShow] = useState(false);
  const target = useRef(null);
  return (
    <>
      <Button ref={target} onClick={() => setShow(!show)}>
        Click me!
      </Button>
      <Overlay target={target.current} show={show} placement="right">
        {(props) => (
          <Tooltip id="overlay-example" {...props}>
            My Tooltip
          </Tooltip>
        )}
      </Overlay>
    </>
  );
}
render(<Example />);

Or pass a Tooltip element to OverlayTrigger instead.

<>
  {['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>
  ))}
</>

<>
  {['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>
  ))}
</>

Popovers

A popover component, like those found in iOS.

const popover = (
  <Popover id="popover-basic">
    <Popover.Header as="h3">Popover right</Popover.Header>
    <Popover.Body>
      And here's some <strong>amazing</strong> content. It's very engaging.
      right?
    </Popover.Body>
  </Popover>
);

const Example = () => (
  <OverlayTrigger trigger="click" placement="right" overlay={popover}>
    <Button variant="success">Click me to see</Button>
  </OverlayTrigger>
);

render(<Example />);

const popover = (
  <Popover id="popover-basic">
    <Popover.Header as="h3">Popover right</Popover.Header>
    <Popover.Body>
      And here's some <strong>amazing</strong> content. It's very engaging.
      right?
    </Popover.Body>
  </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.

<>
  {['top', 'right', 'bottom', 'left'].map((placement) => (
    <OverlayTrigger
      trigger="click"
      key={placement}
      placement={placement}
      overlay={
        <Popover id={`popover-positioned-${placement}`}>
          <Popover.Header as="h3">{`Popover ${placement}`}</Popover.Header>
          <Popover.Body>
            <strong>Holy guacamole!</strong> Check this info.
          </Popover.Body>
        </Popover>
      }
    >
      <Button variant="secondary">Popover on {placement}</Button>
    </OverlayTrigger>
  ))}
</>

<>
  {['top', 'right', 'bottom', 'left'].map((placement) => (
    <OverlayTrigger
      trigger="click"
      key={placement}
      placement={placement}
      overlay={
        <Popover id={`popover-positioned-${placement}`}>
          <Popover.Header as="h3">{`Popover ${placement}`}</Popover.Header>
          <Popover.Body>
            <strong>Holy guacamole!</strong> Check this info.
          </Popover.Body>
        </Popover>
      }
    >
      <Button variant="secondary">Popover on {placement}</Button>
    </OverlayTrigger>
  ))}
</>

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>

<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

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.

function Example() {
  const [show, setShow] = useState(false);
  const [target, setTarget] = useState(null);
  const ref = useRef(null);

  const handleClick = (event) => {
    setShow(!show);
    setTarget(event.target);
  };

  return (
    <div ref={ref}>
      <Button onClick={handleClick}>Holy guacamole!</Button>

      <Overlay
        show={show}
        target={target}
        placement="bottom"
        container={ref.current}
        containerPadding={20}
      >
        <Popover id="popover-contained">
          <Popover.Header as="h3">Popover bottom</Popover.Header>
          <Popover.Body>
            <strong>Holy guacamole!</strong> Check this info.
          </Popover.Body>
        </Popover>
      </Overlay>
    </div>
  );
}

render(<Example />);

function Example() {
  const [show, setShow] = useState(false);
  const [target, setTarget] = useState(null);
  const ref = useRef(null);
  const handleClick = (event) => {
    setShow(!show);
    setTarget(event.target);
  };
  return (
    <div ref={ref}>
      <Button onClick={handleClick}>Holy guacamole!</Button>
      <Overlay
        show={show}
        target={target}
        placement="bottom"
        container={ref.current}
        containerPadding={20}
      >
        <Popover id="popover-contained">
          <Popover.Header as="h3">Popover bottom</Popover.Header>
          <Popover.Body>
            <strong>Holy guacamole!</strong> Check this info.
          </Popover.Body>
        </Popover>
      </Overlay>
    </div>
  );
}
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 a popper prop with a scheduleUpdate() method that an overlay component can use to reposition itself.

const UpdatingPopover = React.forwardRef(
  ({ popper, children, show: _, ...props }, ref) => {
    useEffect(() => {
      console.log('updating!');
      popper.scheduleUpdate();
    }, [children, popper]);

    return (
      <Popover ref={ref} body {...props}>
        {children}
      </Popover>
    );
  },
);

const longContent = `
  Very long
  Multiline content
  that is engaging and what-not
`;
const shortContent = 'Short and sweet!';

function Example() {
  const [content, setContent] = useState(shortContent);

  useEffect(() => {
    const timerId = setInterval(() => {
      setContent(content === shortContent ? longContent : shortContent);
    }, 3000);

    return () => clearInterval(timerId);
  });

  return (
    <OverlayTrigger
      trigger="click"
      overlay={
        <UpdatingPopover id="popover-contained">{content}</UpdatingPopover>
      }
    >
      <Button>Holy guacamole!</Button>
    </OverlayTrigger>
  );
}

render(<Example />);

const UpdatingPopover = React.forwardRef(
  ({ popper, children, show: _, ...props }, ref) => {
    useEffect(() => {
      console.log('updating!');
      popper.scheduleUpdate();
    }, [children, popper]);
    return (
      <Popover ref={ref} body {...props}>
        {children}
      </Popover>
    );
  },
);
const longContent = `
  Very long
  Multiline content
  that is engaging and what-not
`;
const shortContent = 'Short and sweet!';
function Example() {
  const [content, setContent] = useState(shortContent);
  useEffect(() => {
    const timerId = setInterval(() => {
      setContent(content === shortContent ? longContent : shortContent);
    }, 3000);
    return () => clearInterval(timerId);
  });
  return (
    <OverlayTrigger
      trigger="click"
      overlay={
        <UpdatingPopover id="popover-contained">{content}</UpdatingPopover>
      }
    >
      <Button>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 `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.

OverlayTriggerview source file

import OverlayTrigger from 'react-bootstrap/OverlayTrigger'

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

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. 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.

import Popover from 'react-bootstrap/Popover'

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
body	boolean		When this prop is set, it creates a Popover with a Popover.Body inside passing the children directly to it
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. This is generally provided by the `Overlay` component positioning the popover
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.

import PopoverBody from 'react-bootstrap/PopoverBody'

Name	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.

import PopoverHeader from 'react-bootstrap/PopoverHeader'

Name	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.

Overlays

Overview

Overlay

Creating an Overlay

OverlayTrigger

Customizing trigger behavior

Tooltips

Examples

Popovers

Examples

Disabled elements

Changing containers

Updating position dynamically

API

Overlayview source file

OverlayTriggerview source file

Tooltipview source file

Popoverview source file

PopoverBodyview source file

PopoverHeaderview source file

Overlays#

Overview#

Overlay#

Creating an Overlay#

OverlayTrigger#

Customizing trigger behavior#

Tooltips#

Examples#

Popovers#

Examples#

Disabled elements#

Changing containers#

Updating position dynamically#

API#

Overlay#view source file

OverlayTrigger#view source file

Tooltip#view source file

Popover#view source file

PopoverBody#view source file

PopoverHeader#view source file

Overlays

Overview

Overlay

Creating an Overlay

OverlayTrigger

Customizing trigger behavior

Tooltips

Examples

Popovers

Examples

Disabled elements

Changing containers

Updating position dynamically

API

Overlayview source file

OverlayTriggerview source file

Tooltipview source file

Popoverview source file

PopoverBodyview source file

PopoverHeaderview source file