Positioner

Headless Positioner; covers CSS absolute positioning, visual viewport, collision flipping.


Package	`@vizejs/ui/positioner`
Maturity	stable
Own the source	`vize lib pull positioner`
Requires	context
Aliases	floating, anchor position, collision, arrow, size, safe area
Covers	CSS absolute positioning, visual viewport, collision flipping, safe-area environment insets

Usage

import { Positioner, PositionerArrow } from "@vizejs/ui/positioner";

Or copy the source into your project with vize lib pull positioner (see Source Distribution).

API

`Positioner`

Source: src/families/overlays/positioner/positioner.vue

Props

Prop	Type	Default	Description
`reference`	`PositionerElement \| null`	`null`	Reference element or virtual box the floating content is placed against.
`placement`	`Placement`	`"bottom"`	Preferred placement before collision handling.
`strategy`	`PositionerStrategy`	`"fixed"`	CSS positioning mode published on the floating host.
`offset`	`number`	`0`	Gap on the main axis between reference and floating.
`collisionPadding`	`number`	`0`	Viewport padding the floating element should not cross.
`arrowPadding`	`number`	`0`	Inset kept between the arrow and floating edges.
`direction`	`"ltr" \| "rtl"`	`"ltr"`	Writing direction used to resolve start/end alignment.
`flip`	`boolean`	`true`	Flip to the opposite side when the preferred side overflows more.
`shift`	`boolean`	`true`	Shift the floating box back into the viewport after flip.
`size`	`boolean`	`false`	Constrain the host to the available space with `max-width`/`max-height` and publish `--vize-ui-positioner-available-width` and `--vize-ui-positioner-available-height` custom properties.
`safeArea`	`boolean`	`false`	Inset the active viewport by `env(safe-area-inset-*)` before collision handling, keeping floating content clear of notches and rounded corners.
`hide`	`boolean`	`true`	Hide when the reference no longer intersects the viewport.
`updateOnScroll`	`boolean`	`true`	Recalculate while ancestors scroll.
`updateOnResize`	`boolean`	`true`	Recalculate when the document or visual viewport resizes.
`viewport`	`Rect`	`undefined`	Viewport used for flip, shift, and hide. Defaults to the visual viewport.

Slots

Slot	Slot props	Description
`default`	`{ readonly placement: Placement; readonly ready: boolean }`	Floating contents. Receives resolved placement for styling hooks.

Exposed

Member	Type	Description
`arrowStyle`	—
`availableHeight`	—
`availableWidth`	—
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`hidden`	—
`ready`	—
`resolvedPlacement`	—
`style`	—
`update`	—
`x`	—
`y`	—

`PositionerArrow`

Source: src/families/overlays/positioner/positioner-arrow.vue

Slots

Slot	Slot props	Description
`default`	`{ readonly x: number \| null; readonly y: number \| null }`	Decorative arrow contents. Receives coordinates for optional custom drawing.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`x`	—
`y`	—

Behavior

Normative state × input → outcome table for positioner.vue and positioner-arrow.vue (@vizejs/ui/positioner). Every row is proven by the named test in src/families/overlays/positioner/positioner.test.ts, src/families/overlays/positioner/positioner-geometry.test.ts, src/families/overlays/positioner/positioner-size.test.ts, src/families/overlays/positioner/positioner-viewport.test.ts, or src/families/overlays/positioner/positioner-ssr.test.ts; compile-only assertions live in src/families/overlays/positioner/positioner.types.test-d.ts.

#	State	Input	Outcome	Proven by
P1	unmeasured	render without a reference	host stays at origin with `ready=false`	`renders a fixed host before the first measure`
P2	unmeasured	virtual reference after mount	coordinates move to the preferred placement	`places below a virtual reference`
P3	overflowing side	`flip`	opposite side is chosen when it overflows less	geometry flip test
P4	overflowing edge	`shift`	floating box is clamped inside the viewport	geometry shift test
P5	off-screen ref	`hide`	`hidden` is true when the reference leaves view	geometry hide test
P6	rtl	`top-start`	start alignment mirrors to the inline-end edge	geometry rtl test
P7	measured	arrow child	arrow is clamped along the facing edge	`clamps the arrow along the facing edge`
P8	any	missing Positioner provider	arrow setup throws a missing-context diagnostic	`rejects an arrow outside Positioner`
P9	present	render	exposed `element` is the rendered node	`exposes the rendered element for composition`
P10	SSR	default render	byte-identical origin markup, no viewport reads	SSR test
P11	public types	invalid placement or mutating readonly refs	compilation rejects misuse	`src/families/overlays/positioner/positioner.types.test-d.ts`
P12	measured	any side	available space stops at the reference edge	`measures available space on every side`
P13	measured	`size`	host publishes max size and custom properties	`constrains the host to the available space when size is enabled`
P14	measured	default `size`	host style stays byte-identical without opt-in	`leaves the host style untouched when size is off`
P15	keyboard open	visual viewport shrinks	floating box stays inside the visible viewport	`keeps the floating box inside the keyboard-shrunk visual viewport`
P16	notched display	`safeArea`	collision handling respects `env(safe-area-inset-*)`	`applies safe-area insets to collision handling`
P17	any	viewport insets	inset math clamps at an empty box	`insets the viewport by per-edge insets`