Overlay

Overlay components codify design patterns related to floating surfaces such as Dialogs and menus.

React
readyNot reviewed for a11y
Rails
readyNot reviewed for a11y

Overlay is an internal component and is intended to be used as a private API, composing other components. It is not intended to be used on its own. If you are looking for a standalone overlay component, consider using AnchoredOverlay or Dialog.

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

React examples

Dialog Overlay

Props

Overlay

NameRequiredDescription
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'
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'
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`.
maxWidth
| 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'
Sets the maximum width of the `Overlay`, pick from our set list of widths. `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `480px`, `xlarge` corresponds to `640px`, `xxlarge` corresponds to `960px`.
visibility
| 'visible' | 'hidden'
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
The top CSS property of the Overlay — affects the vertical position.
left
number
The 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'
The 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`.
overflow
'hidden' | 'scroll' | 'auto' | 'visible'
preventOverflow
boolean
Determines if the Overlay width should be adjusted responsively if `width` is set to either `auto`, `medium` or lower and there is not enough space to display the Overlay. If `preventOverflow` is set to `false`, the Overlay will be displayed at the maximum width that fits within the viewport.
role
ARIA role - will most often be 'dialog' or 'menu'
ARIA role to use for the overlay
data-test-id
unknown
sx
SystemStyleObject