useLayer · astryx-svelte

useLayer @astryx-svelte/core v0.3.0 · 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
 
import { Layer } from '@astryx-svelte/core';

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: render the layer inline (no portal) so it inherits the trigger's theme cascade and keeps a natural focus order. Use `as: "span"` when the layer must be valid inside inline contexts like a paragraph.
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.

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; `bind:this` on a component yields the instance rather than its element.Upstream declares `RefCallback<HTMLElement> \| undefined`.
`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. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. 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 `(children: ReactNode, props: ContextRenderProps \| FixedRenderProps) => ReactNode`.

Examples

Common configurations, variations, and states.

useLayer — Anchored Layer

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