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.

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 using the AnchoredOverlay component or customizing the portal root to achieve different positioning behavior.

The position of the Overlay can be customized by using the position prop in conjunction with the top|left|right|bottom props.

Props

Overlay

React.RefObject<HTMLElement>

function

function

React.RefObject<HTMLElement> []

React.RefObject<HTMLElement>

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

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

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

| 'visible' | 'hidden'

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

number

number

number

number

| 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'

string

SystemStyleObject

Status

Alpha

• Component props and basic example usage of the component 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 robust unit test coverage (100% where achievable).
• Component has visual regression coverage of its default and interactive states.
• Component does not introduce any axe violations.
• Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

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 does not introduce any performance regressions.

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.
• Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.