# components/floating/useAnchoredPosition (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/components/floating/useAnchoredPosition.ts](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts).

## Functions

### `anchorNudge`

Function.

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.

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

**Parameters**

- `side` (`Side`): The side of the anchor the surface is placed on.
- `px` (`number`): 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.

Source: [ui/src/components/floating/useAnchoredPosition.ts:42](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L42)

### `placeSurface`

Function.

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.

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

**Parameters**

- `a` (`Rect`): The anchor's rectangle.
- `size` (`{ height: number; width: number }`): The surface's measured width and height.
- `side` (`Side`): The preferred side of the anchor.
- `align` (`Align`): How the surface lines up along the anchor's edge.
- `offset` (`number`): 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.

Source: [ui/src/components/floating/useAnchoredPosition.ts:86](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L86)

### `useAnchoredPosition`

Function.

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.

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

**Parameters**

- `open` (`boolean`): Whether the surface is shown. No placement is computed while it is closed.
- `anchor` (`Anchor`): The element or point to place against.
- `surfaceRef` (`RefObject<HTMLElement | null>`): Ref to the surface element, measured for its size.
- `options?` (`{ align?: Align; offset?: number; side?: Side }`, default `{}`): 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.

Source: [ui/src/components/floating/useAnchoredPosition.ts:142](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L142)

## Interfaces

### `Placement`

Interface.

Where [`useAnchoredPosition`](https://zidane.si/docs/reference/ui-components-floating-use-anchored-position.md#useAnchoredPosition) puts a surface, in viewport coordinates.

```ts
interface Placement
```

**Properties**

- `left` (`number`): Distance from the viewport's left edge, in px.
- `origin` (`string`): CSS transform-origin that grows the surface out of its anchor.
- `side` (`Side`): The side actually used, which differs from the preferred one when the surface was flipped.
- `top` (`number`): Distance from the viewport's top edge, in px.

Source: [ui/src/components/floating/useAnchoredPosition.ts:20](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L20)

### `Rect`

Interface.

A rectangle in viewport coordinates, like a `DOMRect`.

```ts
interface Rect
```

**Properties**

- `bottom` (`number`): Bottom edge.
- `height` (`number`): Height.
- `left` (`number`): Left edge.
- `right` (`number`): Right edge.
- `top` (`number`): Top edge.
- `width` (`number`): Width.

Source: [ui/src/components/floating/useAnchoredPosition.ts:50](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L50)

## Types

### `Align`

Type.

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

```ts
type Align = 'start' | 'center' | 'end'
```

Source: [ui/src/components/floating/useAnchoredPosition.ts:12](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L12)

### `Anchor`

Type.

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

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

Source: [ui/src/components/floating/useAnchoredPosition.ts:17](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L17)

### `Side`

Type.

The side of the anchor a surface is placed on.

```ts
type Side = 'top' | 'bottom' | 'right' | 'left'
```

Source: [ui/src/components/floating/useAnchoredPosition.ts:10](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/useAnchoredPosition.ts#L10)