Location Ref

---
title: Location Ref
description: API reference for location references in Plate.
---

Location references are objects that keep specific locations (paths, points, or ranges) in a document synced over time as new operations are applied to the editor. You can access their `current` property at any time for the up-to-date location value. You can access their `current` property at any time for the up-to-date location value.

## Types

### `PathRef`

Path reference objects keep a specific path in a document synced over time. Created using `editor.api.pathRef`.

<API name="PathRef">
<APIAttributes>
  <APIItem name="current" type="Path | null">
    The current path value, updated as operations are applied.
  </APIItem>
  <APIItem name="affinity" type="'forward' | 'backward' | null">
    The direction to prefer when transforming the path:
    - `'forward'`: Prefer the position after inserted content
    - `'backward'`: Prefer the position before inserted content
    - `null`: No preference
  </APIItem>
  <APIItem name="unref()" type="() => Path | null">
    Call this when you no longer need to sync this path. Returns the final path value.
  </APIItem>
</APIAttributes>
</API>

### `PointRef`

Point reference objects keep a specific point in a document synced over time. Created using `editor.api.pointRef`.

<API name="PointRef">
<APIAttributes>
  <APIItem name="current" type="Point | null">
    The current point value, updated as operations are applied.
  </APIItem>
  <APIItem name="affinity" type="'forward' | 'backward' | null">
    The direction to prefer when transforming the point:
    - `'forward'`: Prefer the position after inserted content
    - `'backward'`: Prefer the position before inserted content
    - `null`: No preference
  </APIItem>
  <APIItem name="unref()" type="() => Point | null">
    Call this when you no longer need to sync this point. Returns the final point value.
  </APIItem>
</APIAttributes>
</API>

### `RangeRef`

Range reference objects keep a specific range in a document synced over time. Created using `editor.api.rangeRef`.

<API name="RangeRef">
<APIAttributes>
  <APIItem name="current" type="TRange | null">
    The current range value, updated as operations are applied.
  </APIItem>
  <APIItem name="affinity" type="'forward' | 'backward' | 'inward' | 'outward' | null">
    The direction to prefer when transforming the range:
    - `'forward'`: Both points prefer after inserted content
    - `'backward'`: Both points prefer before inserted content
    - `'inward'`: Range tends to stay same size when content is inserted at edges
    - `'outward'`: Range tends to grow when content is inserted at edges
    - `null`: No preference
  </APIItem>
  <APIItem name="unref()" type="() => TRange | null">
    Call this when you no longer need to sync this range. Returns the final range value.
  </APIItem>
</APIAttributes>
</API>

Example usage of a RangeRef:

```typescript
const selectionRef = editor.api.rangeRef(editor.selection, {
  affinity: 'inward',
})
// Operations that might change the selection
Transforms.unwrapNodes(editor)
// Restore the selection using the ref
Transforms.select(editor, selectionRef.unref())
```


## `PathRefApi`

### `transform`

Transform a path reference by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="ref" type="PathRef">
    The path reference to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply. The editor calls this automatically as needed.
  </APIItem>
</APIParameters>
</API>

## `PointRefApi`

### `transform`

Transform a point reference by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="ref" type="PointRef">
    The point reference to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply. The editor calls this automatically as needed.
  </APIItem>
</APIParameters>
</API>

## `RangeRefApi`

### `transform`

Transform a range reference by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="ref" type="RangeRef">
    The range reference to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply. The editor calls this automatically as needed.
  </APIItem>
</APIParameters>
</API>