Location Ref

PreviousNext

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.

Attributes

Collapse all

    The current path value, updated as operations are applied.

    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

    Call this when you no longer need to sync this path. Returns the final path value.

PointRef

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

Attributes

Collapse all

    The current point value, updated as operations are applied.

    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

    Call this when you no longer need to sync this point. Returns the final point value.

RangeRef

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

Attributes

Collapse all

    The current range value, updated as operations are applied.

    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

    Call this when you no longer need to sync this range. Returns the final range value.

Example usage of a RangeRef:

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.

Parameters

Collapse all

    The path reference to transform.

    The operation to apply. The editor calls this automatically as needed.

PointRefApi

transform

Transform a point reference by an operation.

Parameters

Collapse all

    The point reference to transform.

    The operation to apply. The editor calls this automatically as needed.

RangeRefApi

transform

Transform a range reference by an operation.

Parameters

Collapse all

    The range reference to transform.

    The operation to apply. The editor calls this automatically as needed.

LocationOperation
Location Ref - Plate