# useTimelineCursor

> What the keyboard does with an arrangement's cursor: the arrows on the grid, Home and End, Up and Down to pick a track, Alt and the arrows to jump between locators and clip edges, M to add a locator.

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

```ts
import { useTimelineCursor } from "@/hooks/use-timeline-cursor";
```

- Files: `hooks/use-timeline-cursor.ts`
- Depends on: `arrangement`; npm: `@audio-ui/core`, `@audio-ui/react`
- Used by: `arrangement-editor`, `block-timeline`

| Export | Kind | What it is |
| --- | --- | --- |
| `UseTimelineCursorOptions` | interface |  |
| `useTimelineCursor` | function | What the keyboard does with an arrangement's cursor. |

## Usage

`useTimelineCursor` is what the keys do with the cursor. `handleKey` takes M, which adds a locator, and Alt with the arrows, which jump to the next locator or clip edge, of the picked tracks or of every track. `handleArrowKey` takes the plain arrows, Home and End, for when a key reached the view rather than a control with arrows of its own: Left and Right move the cursor on the grid, Up and Down pick a track. Both say whether the key was theirs.

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

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clips, tracks, locators, selectedIds, selectedTracks, duration` | `as useArrangement returns them` |  | What the keys move through. |
| `getPosition, step` | `() => number, number` |  | Where the cursor is, and the grid it moves on. |
| `onSeek, onPickTrack, onAddLocator` | `(seconds) => void, (id) => void, () => void` |  | What the keys ask for. |
| `handleKey, handleArrowKey` | `(event) => boolean` |  | M and Alt with the arrows; the plain arrows, Home and End. |