Skip to main content
Reakit
DocumentationNewsletter
Spectrum
GitHub
GitHub

Popover

Popover is a non-modal dialog that floats around its disclosure. It's commonly used for displaying additional rich content on top of something.

#Installation

npm install reakit

Learn more in Get started.

#Usage

import {
  usePopoverState,
  Popover,
  PopoverDisclosure,
  PopoverArrow
} from "reakit/Popover";

function Example() {
  const popover = usePopoverState();
  return (
    <>
      <PopoverDisclosure {...popover}>Open Popover</PopoverDisclosure>
      <Popover {...popover} aria-label="Welcome">
        <PopoverArrow {...popover} />
        Welcome to Reakit!
      </Popover>
    </>
  );
}

#Abstracting

You can build your own Popover component with a different API on top of Reakit.

import React from "react";
import {
  usePopoverState,
  Popover as BasePopover,
  PopoverDisclosure,
  PopoverArrow
} from "reakit/Popover";

function Popover({ disclosure, ...props }) {
  const popover = usePopoverState();
  return (
    <>
      <PopoverDisclosure {...popover}>
        {disclosureProps =>
          React.cloneElement(React.Children.only(disclosure), disclosureProps)
        }
      </PopoverDisclosure>
      <BasePopover {...popover} {...props}>
        <PopoverArrow {...popover} />
        {props.children}
      </BasePopover>
    </>
  );
}

function Example() {
  return (
    <Popover
      aria-label="Custom popover"
      disclosure={<button>Open custom popover</button>}
    >
      Custom popover
    </Popover>
  );
}

#Accessibility

  • Popover extends the accessibility features of Dialog.
  • PopoverDisclosure extends the accessibility features of DialogDisclosure.

Learn more in Accessibility.

#Composition

Learn more in Composition.

#Props

#usePopoverState

  • visible boolean

    Whether it's visible or not.

  • unstable_animated number | boolean

    If true, animating will be set to true when visible changes. It'll wait for stopAnimation to be called or a CSS transition ends. If it's a number, stopAnimation will be called automatically after given milliseconds.

  • placement "auto-start" | "auto" | "auto-end" | "top-start...

    Actual placement.

  • unstable_fixed boolean | undefined

    Whether or not the popover should have position set to fixed.

  • unstable_flip boolean | undefined

    Flip the popover's placement when it starts to overlap its reference element.

  • unstable_shift boolean | undefined

    Shift popover on the start or end of its reference element.

  • unstable_gutter number | undefined

    Offset between the reference and the popover.

  • unstable_preventOverflow boolean | undefined

    Prevents popover from being positioned outside the boundary.

  • unstable_boundariesElement "scrollParent" | "viewport" | "window" | undefined

    Boundaries element used by preventOverflow.

#Popover

  • modal boolean | undefined

    Toggles Dialog's modal state.

    • Non-modal: preventBodyScroll doesn't work and focus is free.
    • Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.
  • hideOnEsc boolean | undefined

    When enabled, user can hide the dialog by pressing Escape.

  • hideOnClickOutside boolean | undefined

    When enabled, user can hide the dialog by clicking outside it.

  • preventBodyScroll boolean | undefined

    When enabled, user can't scroll on body when the dialog is visible. This option doesn't work if the dialog isn't modal.

  • unstable_initialFocusRef RefObject<HTMLElement> | undefined

    The element that will be focused when the dialog shows. When not set, the first tabbable element within the dialog will be used.

  • unstable_finalFocusRef RefObject<HTMLElement> | undefined

    The element that will be focused when the dialog hides. When not set, the disclosure component will be used.

  • unstable_portal boolean | undefined

    Whether or not the dialog should be rendered within Portal. It's true by default if modal is true.

  • unstable_orphan boolean | undefined

    Whether or not the dialog should be a child of its parent. Opening a nested orphan dialog will close its parent dialog if hideOnClickOutside is set to true on the parent. It will be set to false if modal is false.

4 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • visible boolean

    Whether it's visible or not.

  • unstable_animated number | boolean

    If true, animating will be set to true when visible changes. It'll wait for stopAnimation to be called or a CSS transition ends. If it's a number, stopAnimation will be called automatically after given milliseconds.

  • unstable_stopAnimation () => void

    Stops animation. It's called automatically if there's a CSS transition. It's called after given milliseconds if animated is a number.

  • hide () => void

    Changes the visible state to false

#PopoverArrow

  • size string | number | undefined

    Arrow's size

1 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • placement "auto-start" | "auto" | "auto-end" | "top-start...

    Actual placement.

#PopoverBackdrop

3 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • visible boolean

    Whether it's visible or not.

  • unstable_animated number | boolean

    If true, animating will be set to true when visible changes. It'll wait for stopAnimation to be called or a CSS transition ends. If it's a number, stopAnimation will be called automatically after given milliseconds.

  • unstable_stopAnimation () => void

    Stops animation. It's called automatically if there's a CSS transition. It's called after given milliseconds if animated is a number.

#PopoverDisclosure

  • disabled boolean | undefined

    Same as the HTML attribute.

  • focusable boolean | undefined

    When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

3 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • visible boolean

    Whether it's visible or not.

  • toggle () => void

    Toggles the visible state

  • unstable_referenceRef RefObject<HTMLElement | null>

    The reference element.