# useArrangement

> The state of an arrangement of clips on tracks, with its operations: selection, group moves and copies, split, duplicate, delete, adding and removing tracks, per-track mix and height, and undo and redo over tracks and clips

```bash
npx shadcn@latest add @audio-ui/use-arrangement
```

```ts
import { useArrangement } from "@/hooks/use-arrangement";
```

- Files: `hooks/use-arrangement.ts`, `lib/arrangement-state.ts`
- Depends on: `arrangement`, `undo-history`; npm: `@audio-ui/react`, `@audio-ui/core`, `@audio-ui/engine`
- Used by: `arranged-clip`, `arrangement-editor`, `arrangement-engine`, `arrangement-view`, `block-audio-editor`, `block-device-chain`, `block-mixer`, `block-timeline`, `dawproject`, `device-view`, `mixer-view`, `timeline-markers`, `track-automation`, `use-time-selection`

| Export | Kind | What it is |
| --- | --- | --- |
| `UseArrangementOptions` | interface |  |
| `useArrangement` | function | Holds the state of an arrangement of clips on tracks in a component, and the view of its tracks (the heights set by hand, the folded ones). |

## Usage

The state of an arrangement in a component: its document (the tracks with their mixes, the clips, the tempo, the time signatures, the locators, the loop), its selection, its undo, and the view of its tracks (heights and folds). Every change is a command sent with `dispatch`, applied by `apply(state, command)` from `lib/arrangement-state`, which installs with it.

```tsx
import { useArrangement } from "@/hooks/use-arrangement";

const arrangement = useArrangement({ duration: 64, initialClips, initialTracks, tempo });

arrangement.dispatch({ type: "rename-clip", id: "verse-bass", name: "Bass" });
arrangement.dispatch({ type: "undo" });
// arrangement.clips, .tracks, .selectedIds, .mixOf(trackId), .canUndo, .doc for the engine
```

The document is a plain value: `doc` is what [`useArrangementEngine`](/docs/lib/arrangement-engine) plays and what a project saves. A command that changes nothing records no step, and a gesture (a drag) is one step of undo. The hook returns the state's parts and what is read from them (`selectedIds`, `mixOf`, `canUndo`, `canRedo`), `history` for a list of the steps (the documents before each change, the one being made and the ones undone, each a step a menu can go back or forward to with as many `undo` or `redo`), `copyOf` for a time selection's clipboard, and `resizeTrack` and `toggleFold` for the view.

It is the state under the [Arrangement](/docs/components/base/arrangement).