Skip to content

Overlay

Use Overlay to provide a flexible floating surface for displaying transient content such as menus, selection options, dialogs, and more.
  • Alpha
  • Review pending by accessibility team
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 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 using the AnchoredOverlay component or customizing the portal root to achieve different positioning behavior.

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
0Vertical position of the overlay, relative to its closest positioned ancestor (often itsPortal).
left
number
0Horizontal position of the overlay, relative to its closest positioned ancestor (often 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 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.