---
title: "Node Positions"
description: "Learn about Node Positions in Tiptap for document navigation and manipulation. Learn more in the docs!"
canonical_url: "https://tiptap.dev/docs/editor/api/node-positions"
---

# Node Positions

Learn about Node Positions in Tiptap for document navigation and manipulation. Learn more in the docs!

Node Positions (`NodePos`) describe the specific position of a node, its children, and its parent, providing easy navigation between them. Node Positions are heavily inspired by the DOM and are based on ProseMirror's [ResolvedPos](https://prosemirror.net/docs/ref/#model.ResolvedPos) implementation.

## Use Node Positions

The easiest way to create a new Node Position is by using the helper functions in the Editor instance. This way you always use the correct editor instance and have direct access to the API.

```js
// set up your editor somewhere up here

// The NodePosition for the outermost document node
const $doc = editor.$doc

// Get all nodes of type 'heading' in the document
const $headings = editor.$nodes('heading')

// Filter by attributes
const $h1 = editor.$nodes('heading', { level: 1 })

// Pick nodes directly
const $firstHeading = editor.$node('heading', { level: 1 })

// Create a new NodePos via the $pos method when the type is unknown
const $myCustomPos = editor.$pos(30)
```

You can also create your own NodePos instances:

```js
// You need to have an editor instance
// and a position you want to map to
const myNodePos = new NodePos(100, editor)
```

## What can I do with a NodePos?

`NodePos` lets you traverse the document similarly to the document DOM in your browser. You can access parent nodes, child nodes, and sibling nodes.

**Example:** Get and update the content of a `codeBlock` node

```js
// get the first codeBlock from your document
const $codeBlock = editor.$node('codeBlock')

// get the previous NodePos of your codeBlock node
const $previousItem = $codeBlock.before

// easily update the content
$previousItem.content = '<p>Updated content</p>'
```

If you are familiar with the DOM, this example will look familiar:

**Example:** Select list items and insert a new item in a bullet list

```js
// get a bullet list from your doc
const $bulletList = editor.$node('bulletList')

// get all listItems from your bulletList
const $listItems = $bulletList.querySelectorAll('listItem')

// get the last listItem
const $lastListItem = $listItems[0]

// insert a new listItem after the last one
editor.commands.insertContentAt($lastListItem.after, '<li>New item</li>')
```

## API

### NodePos

The NodePos class is the main class you will work with. It describes a specific position of a node, its children, its parent and easy ways to navigate between them. They are heavily inspired by the DOM and are based on ProseMirror's [ResolvedPos](https://prosemirror.net/docs/ref/#model.ResolvedPos) implementation.

#### Methods

| Method             | Arguments                                  | Returns             | Description                                                                                               |
| ------------------ | ------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------- |
| `constructor`      | `pos` (number), `editor` (object)          | `NodePos`           | Creates a new `NodePos` instance at the given position (`pos`) within the specified `editor` instance     |
| `closest`          | `nodeType` (string)                        | `NodePos` or `null` | Finds the closest matching `NodePos` going up the document structure. Returns `null` if no match is found |
| `querySelector`    | `nodeType` (string), `attributes` (object) | `NodePos` or `null` | Finds the first matching `NodePos` going down the document structure. Can be filtered by attributes       |
| `querySelectorAll` | `nodeType` (string), `attributes` (object) | `Array<NodePos>`    | Finds all matching `NodePos` instances going down the document structure. Can be filtered by attributes   |
| `setAttribute`     | `attributes` (object)                      | `NodePos`           | Sets the specified attributes on the current `NodePos`                                                    |

##### constructor

**Arguments**

- `pos` – The position you want to map to
- `editor` – The editor instance you want to use

**Returns** `NodePos`

```js
const myNodePos = new NodePos(100, editor)
```

##### closest

The closest NodePos instance of your NodePosition going up the depth. If there is no matching NodePos, it will return `null`.

**Returns** `NodePos | null`

```js
const closest = myNodePos.closest('bulletList')
```

##### querySelector

The first matching NodePos instance of your NodePosition going down the depth. If there is no matching NodePos, it will return `null`.

You can also filter by attributes via the second attribute.

**Returns** `NodePos | null`

```js
const firstHeading = myNodePos.querySelector('heading')
const firstH1 = myNodePos.querySelector('heading', { level: 1 })
```

##### querySelectorAll

All matching NodePos instances of your NodePosition going down the depth. If there is no matching NodePos, it will return an empty array.

You can also filter by attributes via the second attribute.

**Returns** `Array<NodePos>`

```js
const headings = myNodePos.querySelectorAll('heading')
const h1s = myNodePos.querySelectorAll('heading', { level: 1 })
```

##### setAttribute

Set attributes on the current NodePos.

**Returns** `NodePos`

```js
myNodePos.setAttribute({ level: 1 })
```

#### Properties

| Property      | Type                      | Description                                                                                     |
| ------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
| `node`        | `Node` (ProseMirror Node) | The ProseMirror node at the current `NodePos`                                                   |
| `parent`      | `NodePos`                 | The parent node of the current `NodePos`                                                        |
| `children`    | `Array<NodePos>`          | The child nodes of the current `NodePos`                                                        |
| `firstChild`  | `NodePos` or `null`       | The first child node of the current `NodePos`, or `null` if none exists                         |
| `lastChild`   | `NodePos` or `null`       | The last child node of the current `NodePos`, or `null` if none exists                          |
| `pos`         | `number`                  | The position of the node in the document                                                        |
| `from`        | `number`                  | The starting position of the node                                                               |
| `to`          | `number`                  | The ending position of the node                                                                 |
| `range`       | `number`                  | The range (from–to) of the node at the current `NodePos`                                        |
| `content`     | `string`                  | The content of the node at the current `NodePos`. You can set this to update the node's content |
| `attributes`  | `Object`                  | The attributes of the node at the current `NodePos`                                             |
| `textContent` | `string`                  | The text content of the node at the current `NodePos`                                           |
| `depth`       | `number`                  | The depth (level) of the node in the document structure                                         |
| `size`        | `number`                  | The size of the node at the current `NodePos`                                                   |
| `before`      | `NodePos` or `null`       | The previous node before the current `NodePos`, or `null` if none exists                        |
| `after`       | `NodePos` or `null`       | The next node after the current `NodePos`, or `null` if none exists                             |

##### node

The ProseMirror Node at the current Node Position.

**Returns** `Node`

```js
const node = myNodePos.node
node.type.name // 'paragraph'
```

##### element

The DOM element at the current Node Position.

**Returns** `Element`

```js
const element = myNodePos.element
element.tagName // 'P'
```

##### content

The content of your NodePosition. You can set this to a new value to update the content of the node.

**Returns** `string`

```js
const content = myNodePos.content
myNodePos.content = '<p>Updated content</p>'
```

##### attributes

The attributes of your NodePosition.

**Returns** `Object`

```js
const attributes = myNodePos.attributes
attributes.level // 1
```

##### textContent

The text content of your NodePosition.

**Returns** `string`

```js
const textContent = myNodePos.textContent
```

##### depth

The depth of your NodePosition.

**Returns** `number`

```js
const depth = myNodePos.depth
```

##### pos

The position of your NodePosition.

**Returns** `number`

```js
const pos = myNodePos.pos
```

##### size

The size of your NodePosition.

**Returns** `number`

```js
const size = myNodePos.size
```

##### from

The from position of your NodePosition.

**Returns** `number`

```js
const from = myNodePos.from
```

##### to

The to position of your NodePosition.

**Returns** `number`

```js
const to = myNodePos.to
```

##### range

The range of your NodePosition.

**Returns** `number`

```js
const range = myNodePos.range
```

##### parent

The parent NodePos of your NodePosition.

**Returns** `NodePos`

```js
const parent = myNodePos.parent
```

##### before

The NodePos before your NodePosition. If there is no NodePos before, it will return `null`.

**Returns** `NodePos | null`

```js
const before = myNodePos.before
```

##### after

The NodePos after your NodePosition. If there is no NodePos after, it will return `null`.

**Returns** `NodePos | null`

```js
const after = myNodePos.after
```

##### children

The child NodePos instances of your NodePosition.

**Returns** `Array<NodePos>`

```js
const children = myNodePos.children
```

##### firstChild

The first child NodePos instance of your NodePosition. If there is no child, it will return `null`.

**Returns** `NodePos | null`

```js
const firstChild = myNodePos.firstChild
```

##### lastChild

The last child NodePos instance of your NodePosition. If there is no child, it will return `null`.

**Returns** `NodePos | null`

```js
const lastChild = myNodePos.lastChild
```