# useTimelineGrid

> The grid of an arrangement's timeline: adaptive to the zoom or a fixed division, straight or triplet, snapping or not, its name for a menu button, and the changes Cmd/Ctrl + 1 to 5 make.

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

```ts
import { GRID_KEYS, GRID_DIVISION_OPTIONS, useTimelineGrid } from "@/hooks/use-timeline-grid";
```

- Files: `hooks/use-timeline-grid.ts`
- Depends on: nothing; npm: `@audio-ui/engine`
- Used by: `arrangement-editor`, `arrangement-view`, `block-timeline`

| Export | Kind | What it is |
| --- | --- | --- |
| `GridChange` | type | A change of the grid: finer or wider, triplets, snapping, or a grid fixed where it is (and following the zoom again). |
| `GRID_KEYS` | const | Cmd/Ctrl + 1 to 5, by the key's place (`KeyboardEvent.code`) so it works on any keyboard layout. |
| `GRID_DIVISION_OPTIONS` | const | The divisions a grid menu lists, as `TimelineGridMenuItems` takes them: adaptive, which follows the zoom, then the fixed ones. |
| `UseTimelineGridOptions` | interface |  |
| `useTimelineGrid` | function | The grid of an arrangement's timeline: adaptive (lines as close as its density lets them at the zoom) or a fixed division, straight or triplet, snapping or not. |

## Usage

```tsx
import { useTimelineGrid } from "@/hooks/use-timeline-grid";
import { useTimelineZoom } from "@/hooks/use-timeline-zoom";

const viewportRef = useRef<HTMLDivElement>(null);
const view = useTimelineZoom({ duration, viewportRef });
const grid = useTimelineGrid({ tempo, zoom: view.zoom });

<Timeline duration={duration} snapStep={grid.snapStep} {...view.timeline}>
  <TimelineViewport ref={viewportRef}>{/* the lanes draw a line every grid.step */}</TimelineViewport>
</Timeline>;
```

`useTimelineGrid` is the grid: adaptive or a fixed division, triplet, snapping. `step` is what the lanes draw, `snapStep` what gestures snap to (0 with snapping off), and `label` names it for the button that opens `TimelineGridMenuItems` with `GRID_DIVISION_OPTIONS`. `change` is what Cmd/Ctrl + 1 to 5 do, by the key's place in `GRID_KEYS`: a finer or wider grid, triplets, snapping, and a grid fixed where it is or following the zoom again.

It is one of the parts the [Arrangement](/docs/components/base/arrangement) composes.