docs-app/content/docs/examples/library-api-example.mdx

---
seo:
  title: TinaDocs – Type Definition
title: Library (API) Example
last_edited: '2025-07-15T07:43:31.405Z'
tocIsHidden: false
---

> This example content is a random page taken from the [PlateJS documentation](https://platejs.org/docs/api/slate/location-ref).

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`.

<typeDefinition
  property={[
    {
      name: "current",
      description: "The current path value, updated as operations are applied.\n",
      type: "Path | null",
      required: true,
      experimental: false,
      typeUrl: ""
    },
    {
      name: "affinity",
      description:
        "The direction to prefer when transforming the path:\n\n* 'forward': Prefer the position after inserted content\n* 'backward': Prefer the position before inserted content\n* null: No preference\n",
      type: "'forward' | 'backward' | null",
      required: false,
      experimental: false
    },
    {
      name: "unref( )",
      description:
        "Call this when you no longer need to sync this path. Returns the final path value.\n",
      type: "( ) => Path | null"
    }
  ]}
/>

#### `PointRef`

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

<typeDefinition
  property={[
    {
      name: "current",
      description:
        "The current point value, updated as operations are applied.\n",
      type: "Point | null",
      required: true,
      experimental: false,
      typeUrl: ""
    },
    {
      name: "affinity",
      description:
        "The direction to prefer when transforming the point:\n\n* 'forward': Prefer the position after inserted content\n* 'backward': Prefer the position before inserted content\n* null: No preference\n",
      type: "'forward' | 'backward' | null",
      required: false,
      experimental: false
    },
    {
      name: "unref( )",
      description:
        "Call this when you no longer need to sync this point. Returns the final point value.\n",
      type: "( ) => Point | null"
    }
  ]}
/>

#### `RangeRef`

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

<typeDefinition
  property={[
    {
      name: "current",
      description:
        "The current range value, updated as operations are applied.\n",
      type: "TRange | null",
      required: true,
      experimental: false,
      typeUrl: ""
    },
    {
      name: "affinity",
      description:
        "The direction to prefer when transforming the range:\n\n* 'forward': Both points prefer after inserted content\n* 'backward': Both points prefer before inserted content\n* 'inward': Range tends to stay same size when content is inserted at edges\n* 'outward': Range tends to grow when content is inserted at edges\n* null: No preference\n",
      type: "'forward' | 'backward' | 'inward' | 'outward' | null",
      required: false,
      experimental: false
    },
    {
      name: "unref( )",
      description:
        "Call this when you no longer need to sync this range. Returns the final range value.\n",
      type: "( ) => TRange | null"
    }
  ]}
/>

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.

<typeDefinition
  property={[
    {
      name: "ref",
      description: "The path reference to transform.\n",
      type: "PathRef",
      required: true,
      experimental: false,
      typeUrl: ""
    },
    {
      name: "op",
      description:
        "The operation to apply. The editor calls this automatically as needed.\n",
      type: "Operation",
      required: true,
      experimental: false
    }
  ]}
/>

## `PointRefApi`

***

#### `transform`

Transform a point reference by an operation.

<typeDefinition
  property={[
    {
      name: "ref",
      description: "The point reference to transform.\n",
      type: "PointRef",
      required: true,
      experimental: false,
      typeUrl: ""
    },
    {
      name: "op",
      description:
        "The operation to apply. The editor calls this automatically as needed.\n",
      type: "Operation",
      required: true,
      experimental: false
    }
  ]}
/>

## `RangeRefApi`

***

#### `transform`

Transform a range reference by an operation.

<typeDefinition
  property={[
    {
      name: "ref",
      description: "The range reference to transform.\n",
      type: "RangeRef",
      required: true,
      experimental: false,
      typeUrl: ""
    },
    {
      name: "op",
      description:
        "The operation to apply. The editor calls this automatically as needed.\n",
      type: "Operation",
      required: true,
      experimental: false
    }
  ]}
/>