Overlay

Use Overlay to provide a flexible floating surface for displaying transient content such as menus, selection options, dialogs, and more.
  • Alpha
  • Not reviewed for accessibility
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

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

NameTypeDefaultDescription
returnFocusRef Required
React.RefObject<HTMLElement>
Ref for the element to focus when the `Overlay` is closed.
onClickOutside Required
function
Function to call when clicking outside of the `Overlay`. Typically this function sets the `Overlay` visibility state to `false`.
onEscape Required
function
Function to call when user presses `Escape`. Typically this function sets the `Overlay` visibility state to `false`.
ignoreClickRefs
React.RefObject<HTMLElement> []
An array of ref objects to ignore clicks on in the onOutsideClick behavior. This is often used to ignore clicking on the element that toggles the open/closed state for the Overlay to prevent the Overlay from being toggled twice.
initialFocusRef
React.RefObject<HTMLElement>
Ref for the element to focus when the `Overlay` is opened. If nothing is provided, the first focusable element in the `Overlay` body is focused.
width
| 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | 'auto'
'auto'Sets the width of the `Overlay`, pick from our set list of widths, or pass `auto` to automatically set the width based on the content of the `Overlay`. `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `480px`, `xlarge` corresponds to `640px`, `xxlarge` corresponds to `960px`.
height
| 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'auto'
'auto'Sets the height of the `Overlay`, pick from our set list of heights, or pass `auto` to automatically set the height based on the content of the `Overlay`. `xsmall` corresponds to `192px`, `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `432px`, `xlarge` corresponds to `600px`.
maxHeight
| 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'
Sets the maximum height of the `Overlay`, pick from our set list of heights. `xsmall` corresponds to `192px`, `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `432px`, `xlarge` corresponds to `600px`.
visibility
| 'visible' | 'hidden'
'visible'Sets the visibility of the `Overlay`.
anchorSide
| 'inside-top' | 'inside-bottom' | 'inside-left' | 'inside-right' | 'inside-center' | 'outside-top' | 'outside-bottom' | 'outside-left' | 'outside-right'
If provided, the Overlay will slide into position from the side of the anchor with a brief animation
top
number
0The top CSS property of the Overlay — affects the vertical position.
left
number
0The left CSS property of the Overlay — affects the horizontal position.
right
number
The right CSS property of the Overlay — affects the horizontal position.
bottom
number
The bottom CSS property of the Overlay — affects the vertical position.
position
| 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'
absoluteThe position CSS property of the Overlay — sets how the Overlay is positioned relative to its Portal
portalContainerName
string
If defined, Overlays will be rendered in the named portal. See also `Portal`.
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

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.