useOverlayTrigger

Handles the behavior and accessibility for an overlay trigger, e.g. a button that opens a popover, menu, or other overlay that is positioned relative to the trigger.

install	`yarn add @react-aria/overlays`
version	3.7.3
usage	`import {useOverlayTrigger} from '@react-aria/overlays'`

View ARIA spec

W3C

API#

useOverlayTrigger(
  props: OverlayTriggerProps,
  state: OverlayTriggerState,
  ref: RefObject<HTMLElement>
): OverlayTriggerAria

Features#

There is no built in way to create popovers or other types of overlays in HTML. useOverlayTrigger, combined with useOverlayPosition, helps achieve accessible overlays that can be styled as needed.

Note: useOverlayTrigger only handles the overlay itself. It should be combined with useDialog to create fully accessible popovers. For menus, see useMenuTrigger, which builds on useOverlayTrigger and provides additional functionality specific to menus.

Exposes overlay trigger and connects trigger to overlay with ARIA
Positions the overlay relative to the trigger when combined with useOverlayPosition
Hides content behind the overlay from screen readers when combined with useModal
Handles closing the overlay when interacting outside and pressing the Escape key, when combined with useOverlay

Anatomy#

An overlay trigger consists of a trigger element (e.g. button) and an overlay (e.g. popover, menu, listbox, etc.). useOverlayTrigger handles exposing the trigger and overlay to assistive technology with ARIA. It should be combined with useOverlay to handle closing the overlay, useModal to handle hiding content behind the overlay from screen readers, and optionally with useOverlayPosition to handle positioning the overlay relative to the trigger.

useOverlayTrigger returns props that you should spread onto the trigger element and the appropriate element:

Name	Type	Description
`triggerProps`	`AriaButtonProps`	Props for the trigger element.
`overlayProps`	`HTMLAttributes<HTMLElement>`	Props for the overlay container element.

State is managed by the useOverlayTriggerState hook in @react-stately/overlays. The state object should be passed as an argument to useOverlayTrigger.

Example#

This example shows how to build a typical popover overlay that is positioned relative to a trigger button. The content of the popover is a dialog, built with useDialog.

The popover can be closed by clicking or interacting outside the popover, or by pressing the Escape key. This is handled by useOverlay. When the popover is closed, focus is restored back to its trigger button by a <FocusScope>.

Content outside the popover is hidden from screen readers by useModal. This improves the experience for screen reader users by ensuring that they don't navigate out of context. This is especially important when the popover is rendered into a portal at the end of the document, and the content just before it is unrelated to the original trigger.

To allow screen reader users to more easily dismiss the popover, a visually hidden <DismissButton> is added at the end of the dialog.

The application is contained in an OverlayProvider, which is used to hide the content from screen readers with aria-hidden while an overlay is open. In addition, each overlay must be contained in an OverlayContainer, which uses a React Portal to render the overlay at the end of the document body. If a nested overlay is opened, then the first overlay will also be set to aria-hidden, so that only the top-most overlay is accessible to screen readers.

Note: useModal only hides content within parent OverlayProvider components. However, if you have additional content in your application outside any OverlayProvider, then you should use the @react-aria/aria-modal-polyfill package to ensure that this content is hidden while modals are open as well. See the watchModals docs for more information.

import {useOverlayTriggerState} from '@react-stately/overlays';
import {
  useOverlay,
  useOverlayTrigger,
  useOverlayPosition,
  useModal,
  OverlayProvider,
  OverlayContainer,
  DismissButton
} from '@react-aria/overlays';
import {useDialog} from '@react-aria/dialog';
import {FocusScope} from '@react-aria/focus';
import {useButton} from '@react-aria/button';
import {mergeProps} from '@react-aria/utils';

const Popover = React.forwardRef(
  ({title, children, isOpen, onClose, style, ...otherProps}, ref) => {
    // Handle interacting outside the dialog and pressing
    // the Escape key to close the modal.
    let {overlayProps} = useOverlay(
      {
        onClose,
        isOpen,
        isDismissable: true
      },
      ref
    );

    // Hide content outside the modal from screen readers.
    let {modalProps} = useModal();

    // Get props for the dialog and its title
    let {dialogProps, titleProps} = useDialog({}, ref);

    return (
      <FocusScope restoreFocus>
        <div
          {...mergeProps(overlayProps, dialogProps, otherProps, modalProps)}
          ref={ref}
          style={{
            background: 'white',
            color: 'black',
            padding: 30,
            ...style
          }}>
          <h3 {...titleProps} style={{marginTop: 0}}>
            {title}
          </h3>
          {children}
          <DismissButton onDismiss={onClose} />
        </div>
      </FocusScope>
    );
  }
);

function Example() {
  let state = useOverlayTriggerState({});

  let triggerRef = React.useRef();
  let overlayRef = React.useRef();

  // Get props for the trigger and overlay. This also handles
  // hiding the overlay when a parent element of the trigger scrolls
  // (which invalidates the popover positioning).
  let {triggerProps, overlayProps} = useOverlayTrigger(
    {type: 'dialog'},
    state,
    triggerRef
  );

  // Get popover positioning props relative to the trigger
  let {overlayProps: positionProps} = useOverlayPosition({
    targetRef: triggerRef,
    overlayRef,
    placement: 'top',
    offset: 5,
    isOpen: state.isOpen
  });

  // useButton ensures that focus management is handled correctly,
  // across all browsers. Focus is restored to the button once the
  // popover closes.
  let {buttonProps} = useButton(
    {
      onPress: () => state.open()
    },
    triggerRef
  );

  return (
    <>
      <button {...buttonProps} {...triggerProps} ref={triggerRef}>
        Open Popover
      </button>
      {state.isOpen && (
        <OverlayContainer>
          <Popover
            {...overlayProps}
            {...positionProps}
            ref={overlayRef}
            title="Popover title"
            isOpen={state.isOpen}
            onClose={state.close}>
            This is the content of the popover.
          </Popover>
        </OverlayContainer>
      )}
    </>
  );
}

// Application must be wrapped in an OverlayProvider so that it can be
// hidden from screen readers when an overlay opens.
<OverlayProvider>
  <Example />
</OverlayProvider>

import {useOverlayTriggerState} from '@react-stately/overlays';
import {
  useOverlay,
  useOverlayTrigger,
  useOverlayPosition,
  useModal,
  OverlayProvider,
  OverlayContainer,
  DismissButton
} from '@react-aria/overlays';
import {useDialog} from '@react-aria/dialog';
import {FocusScope} from '@react-aria/focus';
import {useButton} from '@react-aria/button';
import {mergeProps} from '@react-aria/utils';

const Popover = React.forwardRef(
  (
    {
      title,
      children,
      isOpen,
      onClose,
      style,
      ...otherProps
    },
    ref
  ) => {
    // Handle interacting outside the dialog and pressing
    // the Escape key to close the modal.
    let {overlayProps} = useOverlay(
      {
        onClose,
        isOpen,
        isDismissable: true
      },
      ref
    );

    // Hide content outside the modal from screen readers.
    let {modalProps} = useModal();

    // Get props for the dialog and its title
    let {dialogProps, titleProps} = useDialog({}, ref);

    return (
      <FocusScope restoreFocus>
        <div
          {...mergeProps(
            overlayProps,
            dialogProps,
            otherProps,
            modalProps
          )}
          ref={ref}
          style={{
            background: 'white',
            color: 'black',
            padding: 30,
            ...style
          }}>
          <h3 {...titleProps} style={{marginTop: 0}}>
            {title}
          </h3>
          {children}
          <DismissButton onDismiss={onClose} />
        </div>
      </FocusScope>
    );
  }
);

function Example() {
  let state = useOverlayTriggerState({});

  let triggerRef = React.useRef();
  let overlayRef = React.useRef();

  // Get props for the trigger and overlay. This also handles
  // hiding the overlay when a parent element of the trigger scrolls
  // (which invalidates the popover positioning).
  let {triggerProps, overlayProps} = useOverlayTrigger(
    {type: 'dialog'},
    state,
    triggerRef
  );

  // Get popover positioning props relative to the trigger
  let {overlayProps: positionProps} = useOverlayPosition({
    targetRef: triggerRef,
    overlayRef,
    placement: 'top',
    offset: 5,
    isOpen: state.isOpen
  });

  // useButton ensures that focus management is handled correctly,
  // across all browsers. Focus is restored to the button once the
  // popover closes.
  let {buttonProps} = useButton(
    {
      onPress: () => state.open()
    },
    triggerRef
  );

  return (
    <>
      <button
        {...buttonProps}
        {...triggerProps}
        ref={triggerRef}>
        Open Popover
      </button>
      {state.isOpen && (
        <OverlayContainer>
          <Popover
            {...overlayProps}
            {...positionProps}
            ref={overlayRef}
            title="Popover title"
            isOpen={state.isOpen}
            onClose={state.close}>
            This is the content of the popover.
          </Popover>
        </OverlayContainer>
      )}
    </>
  );
}

// Application must be wrapped in an OverlayProvider so that it can be
// hidden from screen readers when an overlay opens.
<OverlayProvider>
  <Example />
</OverlayProvider>

import {useOverlayTriggerState} from '@react-stately/overlays';
import {
  useOverlay,
  useOverlayTrigger,
  useOverlayPosition,
  useModal,
  OverlayProvider,
  OverlayContainer,
  DismissButton
} from '@react-aria/overlays';
import {useDialog} from '@react-aria/dialog';
import {FocusScope} from '@react-aria/focus';
import {useButton} from '@react-aria/button';
import {mergeProps} from '@react-aria/utils';

const Popover = React.forwardRef(
  (
    {
      title,
      children,
      isOpen,
      onClose,
      style,
      ...otherProps
    },
    ref
  ) => {
    // Handle interacting outside the dialog and pressing
    // the Escape key to close the modal.
    let {
      overlayProps
    } = useOverlay(
      {
        onClose,
        isOpen,
        isDismissable: true
      },
      ref
    );

    // Hide content outside the modal from screen readers.
    let {
      modalProps
    } = useModal();

    // Get props for the dialog and its title
    let {
      dialogProps,
      titleProps
    } = useDialog(
      {},
      ref
    );

    return (
      <FocusScope
        restoreFocus>
        <div
          {...mergeProps(
            overlayProps,
            dialogProps,
            otherProps,
            modalProps
          )}
          ref={ref}
          style={{
            background:
              'white',
            color:
              'black',
            padding: 30,
            ...style
          }}>
          <h3
            {...titleProps}
            style={{
              marginTop: 0
            }}>
            {title}
          </h3>
          {children}
          <DismissButton
            onDismiss={
              onClose
            }
          />
        </div>
      </FocusScope>
    );
  }
);

function Example() {
  let state = useOverlayTriggerState(
    {}
  );

  let triggerRef = React.useRef();
  let overlayRef = React.useRef();

  // Get props for the trigger and overlay. This also handles
  // hiding the overlay when a parent element of the trigger scrolls
  // (which invalidates the popover positioning).
  let {
    triggerProps,
    overlayProps
  } = useOverlayTrigger(
    {type: 'dialog'},
    state,
    triggerRef
  );

  // Get popover positioning props relative to the trigger
  let {
    overlayProps: positionProps
  } = useOverlayPosition(
    {
      targetRef: triggerRef,
      overlayRef,
      placement: 'top',
      offset: 5,
      isOpen:
        state.isOpen
    }
  );

  // useButton ensures that focus management is handled correctly,
  // across all browsers. Focus is restored to the button once the
  // popover closes.
  let {
    buttonProps
  } = useButton(
    {
      onPress: () =>
        state.open()
    },
    triggerRef
  );

  return (
    <>
      <button
        {...buttonProps}
        {...triggerProps}
        ref={triggerRef}>
        Open Popover
      </button>
      {state.isOpen && (
        <OverlayContainer>
          <Popover
            {...overlayProps}
            {...positionProps}
            ref={
              overlayRef
            }
            title="Popover title"
            isOpen={
              state.isOpen
            }
            onClose={
              state.close
            }>
            This is the
            content of
            the popover.
          </Popover>
        </OverlayContainer>
      )}
    </>
  );
}

// Application must be wrapped in an OverlayProvider so that it can be
// hidden from screen readers when an overlay opens.
<OverlayProvider>
  <Example />
</OverlayProvider>

Name	Type	Description
`type`	`'dialog' \| 'menu' \| 'listbox' \| 'tree' \| 'grid'`	Type of overlay that is opened by the trigger.

Properties

Name	Type	Description
`isOpen`	`boolean`	Whether the overlay is currently open.

Methods

Method	Description
`open(): void`	Opens the overlay.
`close(): void`	Closes the overlay.
`toggle(): void`	Toggles the overlay's visibility.

Name	Type	Description
`triggerProps`	`AriaButtonProps`	Props for the trigger element.
`overlayProps`	`HTMLAttributes<HTMLElement>`	Props for the overlay container element.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`rel`	`string`	—	The relationship between the linked resource and the current page. See MDN.
`elementType`	`T \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

BaseEvent<ReactKeyboardEvent<any>>

T & {stopPropagation: () => void,
continuePropagation: () => void
}

Handles the behavior and accessibility for an overlay trigger, e.g. a button that opens a popover, menu, or other overlay that is positioned relative to the trigger.

useOverlayTrigger(
  props: OverlayTriggerProps,
  state: OverlayTriggerState,
  ref: RefObject<HTMLElement>
): OverlayTriggerAria

Handles positioning overlays like popovers and menus relative to a trigger element, and updating the position when the window resizes.

useOverlayPosition(
  (props: AriaPositionProps
)): PositionAria

Name	Type	Default	Description
`targetRef`	`RefObject<HTMLElement>`	—	The ref for the element which the overlay positions itself with respect to.
`overlayRef`	`RefObject<HTMLElement>`	—	The ref for the overlay element.
`boundaryElement`	`HTMLElement`	`document.body`	Element that that serves as the positioning boundary.
`scrollRef`	`RefObject<HTMLElement>`	`overlayRef`	A ref for the scrollable region within the overlay.
`shouldUpdatePosition`	`boolean`	`true`	Whether the overlay should update its position automatically.
`onClose`	`() => void`	—	Handler that is called when the overlay should close.
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`offset`	`number`	`0`	The additional offset applied along the main axis between the element and its anchor element.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
`isOpen`	`boolean`	—	Whether the element is rendered.

'bottom'
  | 'bottom left'
  | 'bottom right'
  | 'bottom start'
  | 'bottom end'
  | 'top'
  | 'top left'
  | 'top right'
  | 'top start'
  | 'top end'
  | 'left'
  | 'left top'
  | 'left bottom'
  | 'start'
  | 'start top'
  | 'start bottom'
  | 'right'
  | 'right top'
  | 'right bottom'
  | 'end'
  | 'end top'
  | 'end bottom'

Properties

Name	Type	Description
`overlayProps`	`HTMLAttributes<Element>`	Props for the overlay container element.
`arrowProps`	`HTMLAttributes<Element>`	Props for the overlay tip arrow if any.
`placement`	`PlacementAxis`	Placement of the overlay with respect to the overlay trigger.

Methods

Method	Description
`updatePosition(): void`	Updates the position of the overlay.

Axis | 'center'

'top'
  | 'bottom'
  | 'left'
  | 'right'

Hides content outside the current <OverlayContainer> from screen readers on mount and restores it on unmount. Typically used by modal dialogs and other types of overlays to ensure that only the top-most modal is accessible at once.

useModal(
  (options: ModalOptions
)): ModalAria

Name	Type	Description
`isDisabled`	`boolean`

Name	Type	Description
`modalProps`	`ModalAriaProps`	Props for the modal content element.

Name	Type	Description
`data-ismodal`	`boolean`	Data attribute marks the dom node as a modal for the aria-modal-polyfill.

Provides the behavior for overlays such as dialogs, popovers, and menus. Hides the overlay when the user interacts outside it, when the Escape key is pressed, or optionally, on blur. Only the top-most overlay will close at once.

useOverlay(
  (props: OverlayProps,
  , ref: RefObject<HTMLElement>
)): OverlayAria

Name	Type	Default	Description
`isOpen`	`boolean`	—	Whether the overlay is currently open.
`onClose`	`() => void`	—	Handler that is called when the overlay should close.
`isDismissable`	`boolean`	`false`	Whether to close the overlay when the user interacts outside it.
`shouldCloseOnBlur`	`boolean`	—	Whether the overlay should close when focus is lost or moves outside it.
`isKeyboardDismissDisabled`	`boolean`	`false`	Whether pressing the escape key to close the overlay should be disabled.
`shouldCloseOnInteractOutside`	`( (element: HTMLElement )) => boolean`	—	When user interacts with the argument element outside of the overlay ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the overlay. By default, onClose will always be called on interaction outside the overlay ref.

Name	Type	Description
`overlayProps`	`HTMLAttributes<HTMLElement>`	Props to apply to the overlay container element.
`underlayProps`	`HTMLAttributes<HTMLElement>`	Props to apply to the underlay element, if any.

Manages state for an overlay trigger. Tracks whether the overlay is open, and provides methods to toggle this state.

useOverlayTriggerState(
  (props: OverlayTriggerProps
)): OverlayTriggerState

Name	Type	Description
`isOpen`	`boolean`	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	Whether the overlay is open by default (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	Handler that is called when the overlay's open state changes.

Provides the behavior and accessibility implementation for a dialog component. A dialog is an overlay shown above other content in an application.

useDialog(
  (props: AriaDialogProps,
  , ref: RefObject<HTMLElement>
)): DialogAria

Name	Type	Default	Description
`role`	`'dialog' \| 'alertdialog'`	`'dialog'`	The accessibility role for the dialog.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Name	Type	Description
`dialogProps`	`HTMLAttributes<HTMLElement>`	Props for the dialog container element.
`titleProps`	`HTMLAttributes<HTMLElement>`	Props for the dialog title element.

A FocusScope manages focus for its descendants. It supports containing focus inside the scope, restoring focus to the previously focused element on unmount, and auto focusing children on mount. It also acts as a container for a programmatic focus management interface that can be used to move focus forward and back in response to user events.

Name	Type	Description
`children`	`ReactNode`	The contents of the focus scope.
`contain`	`boolean`	Whether to contain focus inside the scope, so users cannot move focus outside, for example in a modal dialog.
`restoreFocus`	`boolean`	Whether to restore focus back to the element that was focused when the focus scope mounted, after the focus scope unmounts.
`autoFocus`	`boolean`	Whether to auto focus the first focusable element in the focus scope on mount.

A visually hidden button that can be used to allow screen reader users to dismiss a modal or popup when there is no visual affordance to do so.

Name	Type	Description
`onDismiss`	`() => void`	Called when the dismiss button is activated.

An OverlayProvider acts as a container for the top-level application. Any application that uses modal dialogs or other overlays should be wrapped in a <OverlayProvider>. This is used to ensure that the main content of the application is hidden from screen readers if a modal or other overlay is opened. Only the top-most modal or overlay should be accessible at once.

Name	Type	Description
`children`	`ReactNode`

A container for overlays like modals and popovers. Renders the overlay into a Portal which is placed at the end of the document body. Also ensures that the overlay is hidden from screen readers if a nested modal is opened. Only the top-most modal or overlay should be accessible at once.

Name	Type	Default	Description
`children`	`ReactNode`	—
`portalContainer`	`HTMLElement`	`document.body`	The container element in which the overlay portal will be placed.