> For the complete documentation index, see [llms.txt](https://docs.activejs.dev/activejs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.activejs.dev/activejs/fundamentals/units/listunit.md).

# ListUnit

**ListUnit** is a type of [Unit](/activejs/fundamentals/units.md) that only accepts `array` data type as its value. It ensures that at any point of time the value would always be an `array`.

It's based on [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array). It implements all the [Array.prototype](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) methods available in the environment/browser, including polyfills. \
e.g.: `push`, `pop`, `join` and `toString`
 etc. to make working with the stored value a bit easier, when you call these methods they are called on the stored `array` value instead of ListUnit instance.

It also borrows some static methods from [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#) like `values` and `entries`, and implements them as instance members `objectValues` and `objectEntries`, respectively. 

See [API reference](https://api.activejs.dev/classes/listunit) for more details.

|                 |         |
| --------------- | ------- |
| Default value   | `[]`    |
| Value data type | `array` |

### ListUnit vs `array`

ListUnit can not be used as a drop-in replacement for an `array`. You can not directly assign or access properties like `unit[index] = v` instead, you have to use `unit.set(index, v)` and `unit.get(index)`, respectively. See the below comparisons for more clarity.

Apart from that, all the non-mutating methods like `map`, `find`, `findIndex`, etc. work similar to as they would on an array. However mutating-methods have some differences, for one, every mutating method makes the Unit emit a new array instead of mutating the current value. 

Also, `forEach` method has been replaced with `forEvery`, because the extended `Observable` class already has a `forEach` method that is intended for something else entirely. See [API reference](http://localhost:8080/globals.html) for more details.

```typescript
// initialization
const arr = ['🐠']; // an array literal
const unit = new ListUnit({initialValue: ['🐠']}); // value is ['🐠']

arr === unit // false

arr instanceof Array // true
unit instanceof Array // false
Array.isArray(unit) // false

// setting an item
arr[1] = '🐞'
unit.set(1) = '🐞' // this is reactive, creates and dispatches a new array

// pushing an item
arr.push('🐊')
unit.push('🐊') // this is reactive, creates and dispatches a new array

// accessing an item at index 0
arr[0]
unit.get(0)
// or 
unit.first()

// removing an item at index 1
arr.splice(1, 1)
unit.splice(1, 1)
// or
unit.remove(1)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.activejs.dev/activejs/fundamentals/units/listunit.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.