# useControllableState reference

The value / defaultValue / onValueChange pattern as a hook: the one behind every controlled prop of the viewer.

Internal state is used while `value` is `undefined`; `onChange` fires whenever the value changes. The setter is stable. Values must not be functions (a function argument is treated as an updater).

## Used by

- [Controlled state](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/controlled-state.md)

## Import

```ts
import { useControllableState } from '@kingtech/react-pdf-viewer';
```

Signature: `useControllableState(options: UseControllableStateOptions<T>): readonly [T, SetControllableState<T>]` → `readonly [T, SetControllableState<T>]`

## Options

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `T` | — | Yes | The controlled value; `undefined` = uncontrolled. |
| `defaultValue` | `T \| () => T` | — | Yes | Initial value while uncontrolled. |
| `onChange` | `(value: T) => void` | — | No | Called with every change, controlled or not. |
| `name` | `string` | — | No | Prop name used in development warnings. |

## Source

[packages/react-pdf-viewer/src/hooks/useControllableState.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/hooks/useControllableState.ts#L25)