• API Overview
• Package Entry Points
• Core Functions
  • createPositioner()
  • computePosition()
  • autoUpdate()
• Middleware
• Reactive Adapter
• Types
• Errors

API Overview

Symbol	Purpose	Execution mode	Common gotcha
createPositioner()	Lifecycle-owned floating positioning	Sync	Call start() after mount
computePosition()	Low-level geometry computation	Sync	Caller owns CSS application
autoUpdate()	Listen for geometry changes	Sync	Call returned cleanup
createReactivePositioner()	Optional Ripple position readable	Sync	Requires @vielzeug/ripple
Middleware factories	Adjust placement and size	Sync	Order is explicit

Package Entry Points

Import	Purpose
@vielzeug/orbit	Positioner, computation, updates, middleware, and types.
@vielzeug/orbit/reactive	Optional Ripple position adapter.
@vielzeug/orbit/presets	Preset placement and middleware options.
@vielzeug/orbit/devtools	Development overlay.

Core Functions

createPositioner()

function createPositioner(
  reference: ReferenceElement,
  floating: HTMLElement,
  options?: PositionerOptions,
): Positioner;

Creates an unstarted positioner.

Parameter	Type	Description
reference	ReferenceElement	DOM or virtual anchor.
floating	HTMLElement	Positioned element.
options	PositionerOptions	Strategy, clipping, middleware, updates, and application callback.

Returns: Positioner.

import { createPositioner } from '@vielzeug/orbit';

const positioner = createPositioner(trigger, tooltip);
positioner.start();
positioner.dispose();

Member	Return	Contract
start()	void	Starts positioning once.
update()	void	Recomputes and applies position.
getPosition()	ComputePositionResult | null	Latest result; null before first update.
dispose()	void	Stops updates and aborts disposal signal.

computePosition()

function computePosition(
  reference: ReferenceElement,
  floating: HTMLElement,
  options?: ComputePositionOptions,
): ComputePositionResult;

Calculates position without applying DOM styles or creating listeners.

Returns: ComputePositionResult.

autoUpdate()

function autoUpdate(
  reference: ReferenceElement,
  floating: HTMLElement,
  update: () => void,
  options?: AutoUpdateOptions,
): () => void;

Calls update immediately, then on relevant scroll, viewport, resize, and optional animation-frame changes.

Returns: cleanup callback.

Middleware

type Middleware = (state: MiddlewareState) => MiddlewareResult | void;

Built-in factories: arrow, autoPlacement, flip, hide, inline, offset, shift, limitShift, and size.

const middleware = [offset(8), flip(), shift({ padding: 6 }), size()];

middlewareData is Record<string, unknown>; narrow custom data at the consuming boundary.

Reactive Adapter

function createReactivePositioner(
  reference: ReferenceElement,
  floating: HTMLElement,
  options?: Omit<PositionerOptions, 'apply'>,
): ReactivePositioner;

ReactivePositioner.position is Readable<ComputePositionResult | null>.

Types

type PositionStrategy = 'absolute' | 'fixed';

type PositionerOptions = Omit<ComputePositionOptions, 'boundary' | 'containingBlock'> & {
  apply?: (result: ComputePositionResult) => void;
  autoUpdate?: AutoUpdateOptions | false;
  boundary?: Element | Rect | 'clippingAncestors';
  strategy?: PositionStrategy;
};

interface Positioner {
  readonly disposalSignal: AbortSignal;
  dispose(): void;
  readonly disposed: boolean;
  getPosition(): ComputePositionResult | null;
  start(): void;
  update(): void;
  [Symbol.dispose](): void;
}

See source declarations for complete geometry and middleware option types.

Errors

Error	Trigger	Notable properties
OrbitConfigError	Invalid middleware reset configuration	Extends OrbitError
OrbitError	Base Orbit error	instanceof OrbitError narrows Orbit errors