useLayer@astryxdesign/core v0.5.2 · useLayer

Usage

Core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for custom popovers, hover cards, tooltips, and fixed-position layers when higher-level components are not enough.

ts
import {useLayer} from '@astryxdesign/core/Layer'

Best practices

GuidancePractices
Do

Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates.

Do

Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.

Do

Rely on the Popover API top layer to escape ancestor clipping and stacking, and host the layer near its trigger rather than in the body so it inherits the trigger's theme cascade and keeps a natural focus order.

Don't

Implement ARIA patterns directly in a Layer unless you also own the full accessibility behavior.

Parameters

ParamTypeDescription
moderequired
'context' | 'fixed'

Positioning strategy: context uses CSS anchor positioning relative to a trigger ref; fixed uses explicit x/y coordinates.

onShow
() => void

Callback fired when the layer becomes visible.

onHide
() => void

Callback fired when the layer is hidden.

lightDismiss
boolean (default: false)

Whether clicking outside should dismiss the layer using native popover light-dismiss behavior.

lazyMount
boolean (default: false)

Context mode only. Wait until show() to resolve the inline/portal position and mount content; hide unmounts the content while the inert marker remains.

Returns

FieldTypeDescription
refRefCallback<HTMLElement> | undefined

Trigger ref for context mode. Undefined in fixed mode.

anchorIdstring

CSS anchor name for context mode positioning.

show() => void

Imperatively show the layer.

hide() => void

Imperatively hide the layer.

isOpenboolean

Whether the layer is currently open.

idstring

Unique ID for aria-describedby or other ARIA relationships.

render(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode

Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover's own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass positioning: "custom" in context mode to author position styles yourself via style (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. Pass offset (a CSS length; a number is px) in context mode for clearance from the anchor: it applies to both edges of the placement axis, so the gap survives a flip. Layers are flush by default. Context mode first renders an inert <template> marker in matching server and client markup. The final layer stays at that JSX position if its parent is safe; otherwise it is portaled to the nearest ancestor outside paragraphs, links, buttons, inline formatting, and structurally restricted containers. The nearest safe host keeps CSS custom properties inheriting live, while the layer preserves direction and writing mode from its JSX position. By default this resolution occurs after hydration so closed-layer DOM remains available; lazyMount defers it until show() and unmounts the content again on hide while the marker remains. The Popover API promotes the layer to the top layer when shown, so it escapes ancestor clipping and stacking wherever it is hosted. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.

Examples

Common configurations, variations, and states.
useLayer — Anchored Layer
Open in Playground

Low-level anchored overlay rendered with useLayer and a custom surface.