Types
This page documents the canonical shared types, protocols, and data structures exported by v-float.
Core Node Types
FloatingNode
The composite node instance returned by useFloatingNode representing an individual floating surface and its hierarchical relationships.
interface FloatingNode {
/** Stable identity symbol for the node. */
id: FloatingNodeId;
/** Shared reactive element refs. */
refs: FloatingNodeElements;
/** Reactive boolean ref indicating whether the surface is open. */
open: Ref<boolean>;
/** Intrinsic parent node in the composite hierarchy. Null for root nodes. */
parent: Readonly<ShallowRef<FloatingNode | null>>;
/** Immediate child nodes registered under this node. */
children: Readonly<ShallowRef<ReadonlySet<FloatingNode>>>;
/** Links a child node under this parent. Returns a teardown unbind function. */
appendChild: (child: FloatingNode) => () => void;
/** Unlinks a child node from this parent. */
removeChild: (child: FloatingNode) => void;
/** Checks if an event target is contained within this node or any open descendant. */
contains: (target: EventTarget | null) => boolean;
/** Recursively traverses this node and its descendants in depth-first order. */
traverse: (
visitor: (node: FloatingNode, depth: number) => TraverseAction,
options?: TraverseOptions,
depth?: number,
) => boolean;
}
FloatingNodeElements
Reactive element references owned by a floating node.
interface FloatingNodeElements {
anchorEl: Ref<AnchorElement>;
floatingEl: Ref<FloatingElement>;
arrowEl: Ref<HTMLElement | null>;
}
AnchorElement
type AnchorElement = HTMLElement | VirtualElement | null;
FloatingElement
type FloatingElement = HTMLElement | null;
FloatingNodeId
type FloatingNodeId = symbol;
VirtualElement
A synthetic anchor element that implements getBoundingClientRect() for coordinate-based positioning (such as cursor tracking or canvas areas).
interface VirtualElement {
getBoundingClientRect: () => DOMRect | ClientRect;
contextElement?: Element;
}
Tree Traversal Types
TraverseAction
Controls the flow of tree traversal inside a traverse() visitor callback.
type TraverseAction = void | "skip" | "stop";
void/undefined: Continues traversal to the next node."skip": In"top-down"order, skips descending into the current node's children while continuing sibling traversal."stop": Immediately terminates the entire traversal across all nodes.
TraverseOptions
interface TraverseOptions {
/**
* Traversal order:
* - `"top-down"` (default / pre-order): visits the parent before its children.
* - `"bottom-up"` (post-order): visits children before their parent.
*/
order?: "top-down" | "bottom-up";
}
Keyboard Navigation Protocol
NavigationTarget
The minimal polymorphic navigation contract implemented by both useRovingFocus and useAriaActivedescendant. Allows auxiliary composables like useTypeahead to coordinate focus seamlessly.
interface NavigationTarget {
/** Currently active or focused item index (-1 when unfocused / idle). */
readonly activeIndex: Readonly<Ref<number>>;
/**
* Polymorphic navigation method to activate a specific item or move directionally.
*/
focusIndex: (target: NavigationTargetValue, options?: NavigationTargetOptions) => void;
}
NavigationTargetValue
Target destination or directional step accepted by focusIndex().
type NavigationTargetValue =
number | "next" | "prev" | "previous" | "first" | "last" | "page-up" | "page-down" | "reset";
NavigationTargetOptions
interface NavigationTargetOptions {
/** Whether to prevent scrolling the newly focused element into view. */
preventScroll?: boolean;
}
RovingEntryFocusMode
type RovingEntryFocusMode = "entry-index" | "last-focused";
TypeaheadFindMatchFn
Custom query matcher callback for useTypeahead.
type TypeaheadFindMatchFn = (
items: readonly (string | null)[],
query: string,
activeIndex: number,
) => number;
VirtualizerAdapter
Adapter interface bridging virtual scroller engines (such as @tanstack/vue-virtual) to useAriaActivedescendant.
interface VirtualizerAdapter {
scrollToIndex: (index: number, options?: { align?: "start" | "center" | "end" | "auto" }) => void;
count: () => number;
isIndexRendered: (index: number) => boolean;
}
Positioning Types
FloatingStyles
Inline styles resolved for the floating panel.
type FloatingStyles = {
position: Strategy;
top: string;
left: string;
transform?: string;
"will-change"?: string;
} & {
[key: `--${string}`]: any;
};
FloatingPosition
Positioning engine return object from usePosition.
interface FloatingPosition {
x: Readonly<Ref<number>>;
y: Readonly<Ref<number>>;
strategy: Readonly<Ref<Strategy>>;
placement: Readonly<Ref<Placement>>;
middlewareData: Readonly<Ref<MiddlewareData>>;
isPositioned: Readonly<Ref<boolean>>;
styles: Readonly<Ref<FloatingStyles>>;
update: () => Promise<void>;
}
ApplyStylesFn
Custom style applicator callback for usePosition({ applyStyles: fn }).
type ApplyStylesFn = (element: HTMLElement, styles: FloatingStyles) => void | (() => void);
UseArrowReturn
Computed arrow coordinates and styles returned by useArrow.
interface UseArrowReturn {
arrowX: ComputedRef<number>;
arrowY: ComputedRef<number>;
arrowStyles: ComputedRef<Record<string, string>>;
}
UseArrowOptions
Options for configuring arrow positioning in useArrow.
interface UseArrowOptions {
offset?: MaybeRefOrGetter<string>;
padding?: MaybeRefOrGetter<Padding>;
applyStyles?: MaybeRef<boolean | undefined> | ApplyArrowStylesFn;
}
ApplyArrowStylesFn
Custom style applicator callback for useArrow({ applyStyles: fn }).
type ApplyArrowStylesFn = (
element: HTMLElement,
styles: Record<string, string>,
) => void | (() => void);
Role & Semantics Types
FloatingRole
type FloatingRole = "dialog" | "grid" | "listbox" | "menu" | "menubar" | "tooltip" | "tree";
FloatingRoleItemRole
type FloatingRoleItemRole =
| "gridcell"
| "group"
| "menuitem"
| "menuitemcheckbox"
| "menuitemradio"
| "none"
| "option"
| "presentation"
| "separator"
| "treeitem";