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

Examples

Default

import React from 'react'
import {useOverlay} from '@primer/react'


interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  children: React.ReactNode
}


const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}


export default function Default() {
  const returnFocusRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)


  return (
    <>
      <button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
        Open overlay
      </button>
      {isOpen && (
        <DemoOverlay returnFocusRef={returnFocusRef} onEscape={closeOverlay} onClickOutside={closeOverlay}>
          <p>Welcome to my overlay.</p>
          <button>Do nothing</button>
          <button
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

import React from 'react'
import {useOverlay} from '@primer/react'

interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  children: React.ReactNode
}

const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}

export default function Default() {
  const returnFocusRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)

  return (
    <>
      <button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
        Open overlay
      </button>
      {isOpen && (
        <DemoOverlay returnFocusRef={returnFocusRef} onEscape={closeOverlay} onClickOutside={closeOverlay}>
          <p>Welcome to my overlay.</p>
          <button>Do nothing</button>
          <button
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

Custom first focused element

import React from 'react'
import {useOverlay} from '@primer/react'


interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  initialFocusRef: React.RefObject<HTMLElement>
  children: React.ReactNode
}


const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, initialFocusRef, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside, initialFocusRef})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}


export default function Default() {
  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(true)}>
        Open overlay
      </button>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
          initialFocusRef={initialFocusRef}
        >
          <div>Overlay content in here</div>
          <button>Do nothing</button>
          <button
            ref={initialFocusRef}
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

import React from 'react'
import {useOverlay} from '@primer/react'

interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  initialFocusRef: React.RefObject<HTMLElement>
  children: React.ReactNode
}

const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, initialFocusRef, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside, initialFocusRef})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}

export default function Default() {
  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(true)}>
        Open overlay
      </button>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
          initialFocusRef={initialFocusRef}
        >
          <div>Overlay content in here</div>
          <button>Do nothing</button>
          <button
            ref={initialFocusRef}
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

Prevent overlay from closing when clicking outside the overlay

import React from 'react'
import {useOverlay} from '@primer/react'


interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  ignoreClickRefs: React.RefObject<HTMLElement>[]
  children: React.ReactNode
}


const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, ignoreClickRefs, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside, ignoreClickRefs})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}


export default function IgnoreClickRefs() {
  const returnFocusRef = React.useRef(null)
  const ignoredClickRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)


  return (
    <>
      <div style={{display: 'flex', gap: '1rem'}}>
        <button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
          Open overlay
        </button>
        <button ref={ignoredClickRef}>Clicking here will not hide the overlay</button>
      </div>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
          ignoreClickRefs={[ignoredClickRef]}
        >
          <p>Welcome to my overlay.</p>
          <button>Do nothing</button>
          <button
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

import React from 'react'
import {useOverlay} from '@primer/react'

interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  ignoreClickRefs: React.RefObject<HTMLElement>[]
  children: React.ReactNode
}

const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, ignoreClickRefs, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside, ignoreClickRefs})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}

export default function IgnoreClickRefs() {
  const returnFocusRef = React.useRef(null)
  const ignoredClickRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)

  return (
    <>
      <div style={{display: 'flex', gap: '1rem'}}>
        <button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
          Open overlay
        </button>
        <button ref={ignoredClickRef}>Clicking here will not hide the overlay</button>
      </div>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
          ignoreClickRefs={[ignoredClickRef]}
        >
          <p>Welcome to my overlay.</p>
          <button>Do nothing</button>
          <button
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

Prevent focus in the overlay when it is opened

import React from 'react'
import {useOverlay} from '@primer/react'


interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  preventFocusOnOpen: boolean
  children: React.ReactNode
}


const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, preventFocusOnOpen, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside, preventFocusOnOpen})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}


export default function Default() {
  const returnFocusRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)


  return (
    <>
      <button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
        Open overlay
      </button>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
          preventFocusOnOpen
        >
          <p>Welcome to my overlay.</p>
          <button>Do nothing</button>
          <button
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

import React from 'react'
import {useOverlay} from '@primer/react'

interface DemoOverlayProps {
  onClickOutside: (e: MouseEvent | TouchEvent) => void
  returnFocusRef: React.RefObject<HTMLElement>
  onEscape: (e: KeyboardEvent) => void
  preventFocusOnOpen: boolean
  children: React.ReactNode
}

const DemoOverlay = ({onClickOutside, returnFocusRef, onEscape, preventFocusOnOpen, children}: DemoOverlayProps) => {
  const overlayProps = useOverlay({returnFocusRef, onEscape, onClickOutside, preventFocusOnOpen})
  return (
    <div
      {...overlayProps}
      style={{
        border: '1px solid',
        margin: '1rem',
        padding: '1rem',
        display: 'flex',
        flexDirection: 'column',
        gap: '1rem',
      }}
    >
      {children}
    </div>
  )
}

export default function Default() {
  const returnFocusRef = React.useRef(null)
  const [isOpen, setIsOpen] = React.useState(false)
  const closeOverlay = () => setIsOpen(false)

  return (
    <>
      <button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
        Open overlay
      </button>
      {isOpen && (
        <DemoOverlay
          returnFocusRef={returnFocusRef}
          onEscape={closeOverlay}
          onClickOutside={closeOverlay}
          preventFocusOnOpen
        >
          <p>Welcome to my overlay.</p>
          <button>Do nothing</button>
          <button
            onClick={() => {
              setIsOpen(false)
            }}
          >
            Close the overlay
          </button>
        </DemoOverlay>
      )}
    </>
  )
}

API

Loading data for useOverlay...