useLayer @astryx-svelte/core v0.5.2 · Layer
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
Best practices
| Guidance | Practices |
|---|---|
| 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
| Parameter | Type | Default | Description |
|---|---|---|---|
mode Required | '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 | false | Whether clicking outside should dismiss the layer using native popover light-dismiss behavior. |
lazyMount | boolean | 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
| Field | Type | Default | Description |
|---|---|---|---|
ref | (node: HTMLElement | null) => void | undefined | — | Trigger ref for context mode. Undefined in fixed mode. Svelte has no ref prop. Reach the element with an attachment through the spread props; |
anchorId | string | — | CSS anchor name for context mode positioning. |
show | () => void | — | Imperatively show the layer. |
hide | () => void | — | Imperatively hide the layer. |
isOpen | boolean | — | Whether the layer is currently open. |
id | string | — | Unique ID for aria-describedby or other ARIA relationships. |
render | (children: string | Snippet, props: ContextRenderProps | FixedRenderProps) => string | Snippet | — | 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. A Svelte hook cannot return markup. This hook returns state only; render its companion component and pass the hook’s value to it.Upstream declares |
Examples
Common configurations, variations, and states.useLayer — Anchored Layer
Low-level anchored overlay rendered with useLayer and a custom surface.