Overlay

Overlay provides component developers a way to position elements globally or relative to a anchor element. The overlay wraps the backdrop, position, exit listener and portal to provide a simple API for handling position.

There are five overlay components in the Overlay:

ConnectedOverlay - A overlay that is relative to a anchoring element.
GlobalOverlay - A overlay that is placed on top of other elements globally.
OverlayPortal - A wrapper around the portal component to manage z-indexs.
OverlayTrigger - The internal trigger component that the ConnectedOverlay uses.

Examples

Global Overlay

A overlay component typically used by components like Dialogs or Drawers. You can use the Global Ovleray using element APIs.

Use the css variable --color-layer-transparent to set the backdrop color.

// index.css
 
body {
  --color-layer-transparent: rgba(0, 0, 0, 0.5);
}

Dialog Example

Below is an example of a simple dialog component using the global overlay.

Connected Overlay

A overlay component typically used by components like menus.

Tooltip Example

Below is an example of simple tooltip component using the connected overlay.

Menu Example

Below is an example of simple menu component using the connected overlay.

API

GlobalOverlay (opens in a new tab)

Prop	Description	Default
`children`	The children to be rendered within the global overlay. `any`
`open` *	If true, the global overlay is open. `boolean`
`closeOnBackdropClick`	If true, the global overlay will close when the backdrop is clicked. `boolean`	`true`
`hasBackdrop`	If true, the global overlay will have a backdrop. `boolean`	`true`
`backdropClassName`	The CSS class name to be applied to the backdrop of the global overlay. `string`
`closeOnEscape`	If true, the global overlay will close when the escape key is pressed. `boolean`	`true`
`onClose`	A function that is called when the global overlay is closed. `() => void`

ConnectedOverlay (opens in a new tab)

Prop	Description	Default
`open` *	Whether the overlay should be visible. `boolean`
`reference`	Reference of the overlay to align to. `ReferenceProp`
`children`	The content of the overlay. `any`
`content` *	Content to render in the overlay. `any`
`trigger`	Type of trigger to open the overlay. `TriggerTypes \| TriggerTypes[]`	`'click' as TriggerTypes`
`triggerElement`	Trigger element to open the overlay. `any`
`triggerClassName`	Trigger classname. `string`
`portalClassName`	Portal classname. `string`
`closeOnBodyClick`	Close when the body is clicked or not. `boolean`
`closeOnEscape`	Close when escape is pressed or not. `boolean`
`appendToBody`	Append the overlay to the body. Almost always want this. `boolean`
`elementType`	Overlay element type. `string`
`modifiers`	Position modifiers. `Modifiers`
`followCursor`	Overlay should follow cursor or not. `boolean`
`placement`	Placement of the overlay. `Placement`
`onOpen`	Event called when the overlay is opened. `(event?: any) => void`
`onClose`	Event called when the overlay is closed. `(event?: any) => void`
`ref`	`LegacyRef<ConnectedOverlayContentRef>`

OverlayTrigger (opens in a new tab)

Prop	Description	Default
`children`	The children to be rendered within the overlay trigger. `any`
`className`	The CSS class name to be applied to the overlay trigger. `string`
`elementType`	The type of element that will be used as the overlay trigger. `any`	`span`
`trigger`	The type(s) of event(s) that will trigger the overlay. Can be a single trigger type or an array of trigger types. `TriggerTypes \| TriggerTypes[]`	`['click']`
`onOpen`	A function that is called when the overlay is opened. It receives an object of type OverlayTriggerEvent as an argument. `(event: OverlayTriggerEvent) => void`	`() => undefined`
`onClose`	A function that is called when the overlay is closed. It receives an object of type OverlayTriggerEvent as an argument. `(event: OverlayTriggerEvent) => void`	`() => undefined`
`ref` *	`LegacyRef<HTMLSpanElement>`

OverlayPortal (opens in a new tab)

Prop	Description	Default
`appendToBody`	If true, the overlay portal will be appended to the body. `boolean`	`true`
`className`	The class name of the overlay portal. `string`
`style`	The style of the overlay portal. `CSSProperties`
`id`	The id of the overlay portal. `string`
`children` *	A function that returns the children of the overlay portal. It receives an object of type OverlayPortalMountEvent as an argument. `(props: OverlayPortalMountEvent) => any`
`onMount`	A function that is called when the overlay portal mounts. It receives an object of type OverlayPortalMountEvent as an argument. `(event: OverlayPortalMountEvent) => void`
`onUnmount`	A function that is called when the overlay portal unmounts. `() => void`
`ref`	Reference to the overlay portal element. `LegacyRef<HTMLElement>`

Typography Portal