# Node API

## Introducing

This is a search result. You cannot to get an access directly. It works like in jQuery: find some node (via Query) and do some action with the found node(s).

Methods which retruns this API:

* [find](/tree/api/tree-api.md#find)
* [findAll](/tree/api/tree-api.md#findall)
* [checked](/tree/api/tree-api.md#checked)
* [selected](/tree/api/tree-api.md#selected)

## Methods

### find

* **Description**: Finds nodes by specified [Query](/tree/api/query.md)
* **Arguments**: 
  * `query`: [Query](/tree/api/query.md)
* **Returns**: 
  * [NodeAPI](/tree/api/node-api.md)
* **Usage:** 

```javascript
// let's find the first child node of 'Awesome Node' which has state 'checked'

this.api
    .find({text: 'Awesome Node'})
    .find({ checked: true })
```

###

### findAll

* **Description**: Similar to `find` method. But it returns all found nodes.
* **Arguments**: 
  * `query`: [Query](/tree/api/query.md)
* **Returns**: 
  * [NodeAPI](/tree/api/node-api.md)
* **Usage:** 

```javascript
// let's find all child nodes of 'Awesome Node' which has state 'checked'

this.api
    .find({text: 'Awesome Node'})
    .findAll({ checked: true })
```

### remove

* **Description**: Removes matched node.
* **Returns:** 
  * `TreeNode`
  * `TreeNode[]`
  * `null`
* **Usage:**

```javascript
this.api.selected().remove()

// how to get null?
this.api.find('not_existed_node').remove()
```

### empty

* **Description**: It removes all children nodes. Also it removes `isBatch` property (see [Acync](/tree/guides/async.md#nodes-property))
* **Returns:** 
  * `boolean`
  * `null`
* **Usage:**

```javascript
this.api.find({ selected: true }).empty()
```

### select

* **Description**: Selects matched node.
* **Arguments:**
  * `extendSelection`**:** boolean not required. For multiple mode adds the matched node to the list of selected items (it's like a selecting node via `Ctrl`)
  * `expandOnSelect` boolean, not required. `select` method will try to read this property from the tree props if **expandOnSelect** argument is not pass
* **Returns:** 
  * `boolean`
  * `null`
* **Usage:**

```javascript
this.api.find('Item 1').select()
this.api.find('Item 2').select(true) // add Item 2 to selected nodes
```

`expandOnSelect` example

```jsx
const data = [
    'Item 1', 'Item 2', 'Item 3'
]

this.api.find(/Item/).select() // selected node: Item 1

// only for multiple mode (!)
this.api.find(/Item 2/).select(true) // selected nodes: Item 1, Item 2

this.api.findAll(/Item/).select() // selected node: Item 3
this.api.findAll(/Item/).select(true) // selected nodes: Item 1, Item 2, Item 3

this.api.find(/Item WITH child/)
    .select(false, true) // it will expand node
```

### unselect

* **Description**: Removes Selection for matched node.
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
// remove all selections
this.api.findAll({ selected: true }).unselect()
```

### check

* **Description**: Sets matched node as ticked(checked).
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
// check all nodes which is not leaf (has children)
this.api.findAll({ isLeaf: false }).check()
```

### uncheck

* **Description**: Sets matched node as **not** ticked(checked).
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
// unchkeck all checked nodes
this.api.checked().uncheck()
```

### disable

* **Description**: Sets matched node as disabled.
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
this.api.find('Item 1').disable()
```

### enable

* **Description**: Sets matched node as enabled.
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
this.api.findAll({ disabled: true }).enable()
```

### enableCheckbox

* **Description**: Sets checkbox state for matched node as enabled.
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
this.api.findAll({ disabledCheckbox: true }).enableCheckbox()
```

### disableCheckbox

* **Description**: Sets checkbox state for matched node as disabled.
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
this.api.findAll({ checked: true }).disableCheckbox()
```

### expand

* **Description**: Expands matched node.
* **Arguments:**
  * `includingDisabled`: boolean (default **false**).
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
this.api.findAll({ expanded: false }).expand(true)
```

### collapse

* **Description**: Collapses matched node.
* **Arguments:**
  * `includingDisabled`: boolean (default **false**). 
* **Returns:** 
  * **`boolean`**
* **Usage:**

```javascript
this.api.findAll({ expanded: true }).collapse()
```

### data

{% hint style="info" %}
You can store here whatever you want. 
{% endhint %}

* **Description**: It is getter/setter for the `data` property of the node.
* **Arguments:**
  * `key`: string | object
  * `value` : any (not required)
* **Returns:** 
  * `undefined`
  * `data object`
  * `TreeNode`
* **Usage:**

```jsx
// tree data
const data = [
    { text: 'Item 1', data: { isSuper: true } },
    { text: 'Item 2' },
    { text: 'Item 3' }
]

// it will find the first item (!)
this.api.find(/Item/).data('isSuper', false)
// or
this.api.find(/Item/).data({ isSuper: false }) // overrides the whole object

// return a value: value (false)
this.api.find(/Item/).data('isSuper')

// get full data object: { isSuper: false }
this.api.find(/Item/).data()

// setter: return NodeAPI
this.api.find(/Item/).data({ isSuper2: false })
// this.api.find(/Item/).data() will return { isSuper: false, isSuper2: false }

// as you can see it's possible you use API after setting the data
this.api.find(/Item/)
    .data('isSuper2', 'string')
    .expand()
```

{% hint style="info" %}
How to **set/get** data for multiple nodes?
{% endhint %}

```javascript
// set isSuper === false for nodes: `Item 2` and `Item 3`
this.api.findAll(/Item (2|3)/).data({ myProp: false })

// Get data for multiple nodes. It will return an array
this.api.findAll(/Item/).data('myProp')
// result will be: [undefined, false, false]
```

### hasClass

* **Description**: Checks if a node has a `className`
* **Arguments:**
  * `className`: string
* **Returns:** 
  * `boolean`
* **Usage:**

```javascript
const hasClass = this.api.find(/excess/).hasClass('highligted')
```

### addClass

* **Description**: It will add classNames for the node. This class will be added to the node with the class `.node-content` (check [Node's structure](/tree/customization.md#nodes-strcutrure))
* **Arguments:**
  * `Array<className>`: string\[]
* **Returns:**&#x20;
  * `TreeNode` if node is found
* **Usage:**

```javascript
this.api.find(/excess/).addClass(['excess-node', 'you-can', 'pass', 'many', 'names'])
this.api.findAll(/excess/).addClass(['red-border'])
```

###

### removeClass

* **Description**: The same behavior as `addClass` method, but it removes classNames
* **Arguments:**
  * `Array<className>`: string\[]
* **Returns:**&#x20;
  * `boolean`
* **Usage:**

```javascript
this.api.find(/excess/).removeClass(['excess-node', 'pass', 'many', 'names'])
this.api.find(/focused/).removeClass(['focused'])
```

### append

* **Description**: Inserts nodes to the end of the matched node
* **Arguments:**
  * `nodes`: *string | object | Promise*
  * `opts`: [Insertion options](/tree/guides/async.md#insertion-options)
* **Returns:**&#x20;
  * `Promiselike<TreeNode[]>` added nodes (always an array)
* **Usage:**

```javascript
const appendedNodes = this.api.find('Item 1').append(
    ['Item 1.1.', 'Item 1.2'], // nodes can be as string
    { expand: true } // expand node with text 'Item 1' (if node was found)
)

this.api.find({ selected: true }).append(
    [
        { text: 'Selected children 1', disabled: true },
        { text: 'Selected children 2' }        
    ]
)

// it also can be a function, but it must return a Promise
this.api.find('Selected children 2').append(
    (node) => {
        // node.text === 'Selected children 2'
        return fetch(`/api?childName=${node.text}`)
            .then(response => response.json())
    }
)
```

###

### prepend

* **Description**: This method is similar to `append`. But nodes inserting to the beginning of children list. (well ... you know, as well as jQuery :) )
* **Example:**

```javascript
// tree structure
/**
item 1
item 2
 item 2.1
 item 2.2
item 3
*/

this.api.find('item 2').append([
 'item 2.3', 'item 2.4', { text: 'item 2.5', checked: true }
])

// will be:
/**
item 1
 item 2.3    << new node
 item 2.4    << new node
 item 2.5    << new node
 item 2.1
 item 2.2
item 2
item 3
*/
```

###

### before

* **Description**: This method is similar to `append`. But nodes inserting **before** matched node.
* **Example:**

```javascript
// tree structure
/**
item 1
item 2
item 3
*/

this.api.find(/item 2/).before(, 'item n')

// will be:
/**
item 1
item n <<<<<<< -- added node
item 2
item 3
*/
```

###

### after

* **Description**: This method is similar to `append`. But nodes inserting **after** matched node.

```javascript
// tree structure
/**
item 1
item 2
item 3
*/

this.api.find(/item 2/).before('item n')

// will be:
/**
item 1
item 2
item n <<<<<<< -- added node
item 3
*/
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://eyzy.gitbook.io/tree/api/node-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.