Overlay

import {Overlay} from '@primer/react'

The Overlay component handles all behaviors needed by overlay UIs as well as the common styles that all overlays should have. Overlay is the base component for many of our overlay-type components. Overlays use shadows to express elevation.

Behaviors include:

• Rendering the overlay in a React Portal so that it always renders on top of other content on the page
• 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 either user provided element, or the first focusable element in the container when it is opened
• Returning focus to an element when container is closed

Example

const Example = () => {
  // you must manage your own open state
  const [isOpen, setIsOpen] = React.useState(false)
  const noButtonRef = React.useRef(null)
  const anchorRef = React.useRef(null)
  return (
    <>
      <Button ref={anchorRef} onClick={() => setIsOpen(!isOpen)}>
        open overlay
      </Button>
      {/* be sure to conditionally render the Overlay. This helps with performance and is required. */}
      {isOpen && (
        <Overlay
          initialFocusRef={noButtonRef}
          returnFocusRef={anchorRef}
          ignoreClickRefs={[anchorRef]}
          onEscape={() => setIsOpen(!isOpen)}
          onClickOutside={() => setIsOpen(false)}
          aria-labelledby="title"
        >
          <Box display="flex" flexDirection="column" p={2}>
            <Text id="title">Are you sure you would like to delete this item?</Text>
            <Button>yes</Button>
            <Button ref={noButtonRef}>no</Button>
          </Box>
        </Overlay>
      )}
    </>
  )
}

render(<Example />)

Accessibility considerations

• The Overlay must either have:
  • A value set for the aria-labelledby attribute that refers to a visible title.
  • An aria-label attribute
• If the Overlay should also have a longer description, use aria-describedby
• The Overlay component has a role="dialog" set on it, if you are using Overlay for alerts, you can pass in role="alertdialog" instead. Please read the W3C guidelines to determine which role is best for your use case
• The Overlay component has aria-modal set to true by default and should not be overridden as all Overlays behave as modals.

See the W3C accessibility recommendations for modals here.

Positioning

Overlay renders its children within a div positioned absolutely within a portal within the default portal root. The overlay will not update its positioning if the portal root's positioning changes (e.g., if the portal root is statically positioned after some DOM element that dynamically resizes). You may consider customizing the portal or specifying a different portal root to achieve different positioning behavior.

Props

Overlay

React.RefObject<HTMLElement>

React.RefObject<HTMLElement>

function

function

React.RefObject<HTMLElement> []

React.RefObject<HTMLElement>

| 'small' 
| 'medium' 
| 'large' 
| 'xlarge' 
| 'xxlarge' 
| 'auto'

| 'xsmall' 
| 'small' 
| 'medium' 
| 'large' 
| 'xlarge' 
| 'auto'

| 'visible' 
| 'hidden'

| 'inside-top' 
| 'inside-bottom' 
| 'inside-left' 
| 'inside-right' 
| 'inside-center' 
| 'outside-top' 
| 'outside-bottom' 
| 'outside-left' 
| 'outside-right'

number

number

string

SystemStyleObject

Status

Alpha

• Component props are documented on primer.style/react.
• Component does not have any unnecessary third-party dependencies.
• Component can adapt to different themes.
• Component can adapt to different screen sizes.
• Component has 100% test coverage.

Beta

• Component is used in a production application.
• Common usage examples are documented on primer.style/react.
• Common usage examples are documented in storybook stories.
• Component has been reviewed by a systems designer and any resulting issues have been addressed.
• Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Stable

• Component API has been stable with no breaking changes for at least one month.
• Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
• Component has corresponding design guidelines documented in the interface guidelines.
• Component has corresponding Figma component in the Primer Web library.