Provides all relevant `Overlay` behavior and provides a ref for the overlay's container.

useOverlay calls all of the relevant behavior Hooks that all Overlay components & composite components should have and returns a ref to be passed down to the overlay's container.

These behaviors include:

  • Correctly positioning the component based on the values provided to positionSettings and positionDeps.
  • Trapping focus
  • Calling a user provided function when the user presses Escape
  • Calling a user provided function when the user clicks outside of the container
  • Focusing the either a user provided element, or the first focusable element in the container when it is opened.
  • Returning focus to an element when container is closed

Note: useOverlay and Overlay do not manage the open state of the overlay. We leave control of the open state up to the user. All behaviors are built with the assumption that the overlay will not be rendered on the page & fully unmounted when it is not visible. See the examples for details on how to conditionally render a component in JSX.



onEscapePressfunctionrequiredFunction to call when user presses the Escape key
onOutsideClickfunctionrequiredFunction to call when user clicks outside of the overlay
ignoreClickRefsReact.RefObject<HTMLElement> []optionalRefs to click clicks on in the onOutsideClick function, useful for ignoring clicks on elements that trigger the overlay visibility.
initialFocusRefReact.RefObject<HTMLElement>optionalRef to focus when overlay is mounted.
returnFocusRefReact.RefObject<HTMLElement>requiredRef to focus when overlay is unmounted. Important for accessibility.