Skip to content
zidane
UI kit reference

components/floating/useAnchoredPosition

import { … } from 'zidane-ui'ui/src/components/floating/useAnchoredPosition.ts

Functions#

anchorNudgeFunction#

Where a surface placed on side starts its enter: px back toward its anchor, so it slides out of it (a menu above its trigger rises, one to the right moves right). Menus nudge 4px, tooltips 2px.

TypeScript
function anchorNudge(side: Side, px: number): { x: number; y: number }

Parameters

Parameters
NameTypeDescription
sideSide

The side of the anchor the surface is placed on.

pxnumber

How far back toward the anchor the enter starts, in px.

Returns

{ x: number; y: number }

The x and y offset to start the enter from.

ui/src/components/floating/useAnchoredPosition.ts:42

placeSurfaceFunction#

Computes where a surface goes next to an anchor. It tries side, flips to the opposite side when side does not fit but the opposite does, then clamps the result 8px inside the viewport.

TypeScript
function placeSurface(
  a: Rect,
  size: { height: number; width: number },
  side: Side,
  align: Align,
  offset: number,
  viewport?: { height: number; width: number },
): Placement

Parameters

Parameters
NameTypeDescription
aRect

The anchor's rectangle.

size{ height: number; width: number }

The surface's measured width and height.

sideSide

The preferred side of the anchor.

alignAlign

How the surface lines up along the anchor's edge.

offsetnumber

Gap between anchor and surface, in px.

viewport?{ height: number; width: number }

The viewport size to fit in. Defaults to the window's inner size.

Returns

Placement

The position, the side used and the transform-origin that grows the surface out of the anchor.

ui/src/components/floating/useAnchoredPosition.ts:86

useAnchoredPositionFunction#

Measures where a surface goes next to its anchor and keeps it current. It re-measures on resize, on scroll outside the surface and when the surface's own size changes.

TypeScript
function useAnchoredPosition(
  open: boolean,
  anchor: Anchor,
  surfaceRef: RefObject<HTMLElement | null>,
  options?: { align?: Align; offset?: number; side?: Side },
): Placement | null

Parameters

Parameters
NameTypeDefaultDescription
openboolean

Whether the surface is shown. No placement is computed while it is closed.

anchorAnchor

The element or point to place against.

surfaceRefRefObject<HTMLElement | null>

Ref to the surface element, measured for its size.

options?{ align?: Align; offset?: number; side?: Side }{}

The preferred side (default bottom), align (default start) and offset in px (default 6).

Returns

Placement | null

The placement, or null while closed or before the first measurement.

ui/src/components/floating/useAnchoredPosition.ts:142

Interfaces#

PlacementInterface#

Where useAnchoredPosition puts a surface, in viewport coordinates.

TypeScript
interface Placement

Properties

Placement properties
NameTypeDescription
leftnumber

Distance from the viewport's left edge, in px.

originstring

CSS transform-origin that grows the surface out of its anchor.

sideSide

The side actually used, which differs from the preferred one when the surface was flipped.

topnumber

Distance from the viewport's top edge, in px.

ui/src/components/floating/useAnchoredPosition.ts:20

RectInterface#

A rectangle in viewport coordinates, like a DOMRect.

TypeScript
interface Rect

Properties

Rect properties
NameTypeDescription
bottomnumber

Bottom edge.

heightnumber

Height.

leftnumber

Left edge.

rightnumber

Right edge.

topnumber

Top edge.

widthnumber

Width.

ui/src/components/floating/useAnchoredPosition.ts:50

Types#

AlignType#

How a surface lines up along the anchor's edge: with its start, its centre or its end.

TypeScript
type Align = 'start' | 'center' | 'end'

ui/src/components/floating/useAnchoredPosition.ts:12

AnchorType#

What a surface is placed against: an element, or a viewport point such as a right-click. An element of null yields no placement.

TypeScript
type Anchor = { element: HTMLElement | null } | { point: { x: number; y: number } }

ui/src/components/floating/useAnchoredPosition.ts:17

SideType#

The side of the anchor a surface is placed on.

TypeScript
type Side = 'top' | 'bottom' | 'right' | 'left'

ui/src/components/floating/useAnchoredPosition.ts:10