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
Figma
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
Dropdown Overlay
Props
Overlay
Name | Required | Description |
---|---|---|
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 |