Site navigation

useOverlay

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.

Usage

const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, ...rest}) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef})
  return <Box height="200px" bg="green.4" {...overlayProps} {...rest} />
}

const DemoComponent = () => {
  const returnFocusRef = React.useRef(null)
  const initialFocusRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)
  return (
    <>
      <Button ref={returnFocusRef} onClick={() => setIsOpen(!isOpen)}>
        toggle
      </Button>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          ignoreClickRefs={[returnFocusRef]}
          initialFocusRef={initialFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
        >
          <Button>Button One</Button>
          <Button ref={initialFocusRef}>Button Two</Button>
        </DemoOverlay>
      )}
    </>
  )
}

render(<DemoComponent />)

const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, ...rest}) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef})
  return <Box height="200px" bg="green.4" {...overlayProps} {...rest} />
}

const DemoComponent = () => {
  const returnFocusRef = React.useRef(null)
  const initialFocusRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)
  return (
    <>
      <Button ref={returnFocusRef} onClick={() => setIsOpen(!isOpen)}>
        toggle
      </Button>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          ignoreClickRefs={[returnFocusRef]}
          initialFocusRef={initialFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
        >
          <Button>Button One</Button>
          <Button ref={initialFocusRef}>Button Two</Button>
        </DemoOverlay>
      )}
    </>
  )
}

render(<DemoComponent />)

UseOverlaySettings

Name	Type	Required	Description
onEscapePress	`function`	required	Function to call when user presses the Escape key
onOutsideClick	`function`	required	Function to call when user clicks outside of the overlay
ignoreClickRefs	`React.RefObject<HTMLElement> []`	optional	Refs to click clicks on in the `onOutsideClick` function, useful for ignoring clicks on elements that trigger the overlay visibility.
initialFocusRef	`React.RefObject<HTMLElement>`	optional	Ref to focus when overlay is mounted.
returnFocusRef	`React.RefObject<HTMLElement>`	required	Ref to focus when overlay is unmounted. Important for accessibility.