# CollectionState

**Category:** Common/State

## API

### Overview

`CollectionState` is the core state object for all collection components. It manages server data fetching, pagination, filtering, sorting, search, and bulk selection. Created by hooks like [`useTableCollection`](./?path=/story/base-components-collections-table-usetablecollection--usetablecollection) or [`useGridCollection`](./?path=/story/common-hooks--usegridcollection).

Key methods: `invalidate()`, `refreshCurrentPage()`, `clearResultAndMoveToStart()`, `retryErrorState()`.

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `invalidate` | `(params?: { filters?: { [P in keyof F]?: string[] \| null \| undefined; } \| undefined; } \| undefined) => void` | Yes | - | Invalidates all cache records for this collection.<br> Optional parameters:<br> `filters` - Clears only a specific part of the cache, for example: `invalidate({ filters: { status: ['active'] } })` |
| `refreshAllPages` | `(params?: { beforeUpdateResult?: (() => unknown) \| undefined; filters?: { [P in keyof F]?: string[] \| null \| undefined; } \| undefined; } \| undefined) => Promise<void>` | Yes | - | Invalidates cache and refreshes all previously fetched pages, without showing a loading indication.<br> Optional parameters:<br> - `beforeUpdateResult` - A callback function that will be called before updating the result.<br> - `filters` - Invalidates only a specific part of the cache, for example: `refreshAllPages({ filters: { status: ['active'] } })`. |
| `refreshCurrentPage` | `(params?: { noInvalidate?: boolean \| undefined; } \| undefined) => Promise<void>` | Yes | - | Invalidates cache and refreshes current page, without showing a loading indication.<br> Optional parameters:<br> - `noInvalidate` - Refreshes current page without invalidating cache. |
| `clearResultAndMoveToStart` | `(params?: { force?: boolean \| undefined; filters?: { [P in keyof F]?: string[] \| null \| undefined; } \| undefined; } \| undefined) => Promise<void>` | Yes | - | Clears all data from the collection and goes back to the first page and refreshes the first page data, while showing a loading indication.<br> Optional parameters:<br> - `force` - Invalidates the cache and resets react-query observer. - `filters` - Clears only a specific part of the cache, for example: `invalidate({ filters: { status: ['active'] } })` |
| `retryErrorState` | `() => void` | Yes | - | Triggers retry when collection fails to load |
| `bulkSelect` | `BulkSelectState<T>` | Yes | - | [BulkSelectState](./?path=/story/common-state--bulkselectstate) |
| `searchInputRef` | `{ focus: () => void; } \| null` | No | - | Reference to the search input element to allow programmatic focus |
| `originQuery` | `ComputedQueryFull<F>` | Yes | - | [ComputedQuery](./?path=/story/common-types--computedquery) instance. Holds all the relevant variables to query the server API with. |
| `status` | `QueryResultStatus<DataResultKeyed<T>, unknown>` | Yes | - | Status of the query. Contains boolean flags of `isIdle`, `isError`, `isLoading`, `isFetching`, `isSuccess`. The difference between `isLoading` and `isFetching` is that `isLoading` is true during the initial query, `isFetching` is true during the next queries. |
| `total` | `number` | Yes | - | The total number of items, as was returned from the last query. |
| `keyedItems` | `KeyedItem<T>[]` | Yes | - | All the keyed items of the collection |
| `getItem` | `(key: string) => T \| null \| undefined` | Yes | - | Get an item object according to its key @param key The key of the wanted item @returns The wanted item |