Docs
βš™οΈ ⏐ Utils
Overlay

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)

PropDescriptionDefault
childrenThe children to be rendered within the global overlay.
any
open *If true, the global overlay is open.
boolean
closeOnBackdropClickIf true, the global overlay will close when the backdrop is clicked.
boolean
true
hasBackdropIf true, the global overlay will have a backdrop.
boolean
true
backdropClassNameThe CSS class name to be applied to the backdrop of the global overlay.
string
closeOnEscapeIf true, the global overlay will close when the escape key is pressed.
boolean
true
onCloseA function that is called when the global overlay is closed.
() => void

ConnectedOverlay (opens in a new tab)

PropDescriptionDefault
open *Whether the overlay should be visible.
boolean
referenceReference of the overlay to align to.
ReferenceProp
childrenThe content of the overlay.
any
content *Content to render in the overlay.
any
triggerType of trigger to open the overlay.
TriggerTypes | TriggerTypes[]
'click' as TriggerTypes
triggerElementTrigger element to open the overlay.
any
triggerClassNameTrigger classname.
string
portalClassNamePortal classname.
string
closeOnBodyClickClose when the body is clicked or not.
boolean
closeOnEscapeClose when escape is pressed or not.
boolean
appendToBodyAppend the overlay to the body. Almost always want this.
boolean
elementTypeOverlay element type.
string
modifiersPosition modifiers.
any
followCursorOverlay should follow cursor or not.
boolean
placementPlacement of the overlay.
Placement
onOpenEvent called when the overlay is opened.
(event?: any) => void
onCloseEvent called when the overlay is closed.
(event?: any) => void
ref
LegacyRef<ConnectedOverlayContentRef>

OverlayTrigger (opens in a new tab)

PropDescriptionDefault
childrenThe children to be rendered within the overlay trigger.
any
classNameThe CSS class name to be applied to the overlay trigger.
string
elementTypeThe type of element that will be used as the overlay trigger.
any
span
triggerThe 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']
onOpenA function that is called when the overlay is opened. It receives an object of type OverlayTriggerEvent as an argument.
(event: OverlayTriggerEvent) => void
() => undefined
onCloseA 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)

PropDescriptionDefault
appendToBodyIf true, the overlay portal will be appended to the body.
boolean
true
classNameThe class name of the overlay portal.
string
styleThe style of the overlay portal.
CSSProperties
idThe 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
onMountA function that is called when the overlay portal mounts. It receives an object of type OverlayPortalMountEvent as an argument.
(event: OverlayPortalMountEvent) => void
onUnmountA function that is called when the overlay portal unmounts.
() => void
refReference to the overlay portal element.
LegacyRef<HTMLElement>