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

    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.

    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

    import Overlay from 'react-bootstrap/Overlay'Copy import code for the Overlay component
    NameTypeDefaultDescription
    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.

    OverlayTriggerview source file

    import OverlayTrigger from 'react-bootstrap/OverlayTrigger'Copy import code for the OverlayTrigger component
    NameTypeDefaultDescription
    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'Copy import code for the Tooltip component
    NameTypeDefaultDescription
    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'Copy import code for the Popover component
    NameTypeDefaultDescription
    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.

    PopoverContentview source file

    import PopoverContent from 'react-bootstrap/PopoverContent'Copy import code for the PopoverContent component
    NameTypeDefaultDescription
    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.

    PopoverTitleview source file

    import PopoverTitle from 'react-bootstrap/PopoverTitle'Copy import code for the PopoverTitle component
    NameTypeDefaultDescription
    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.