# useTimeSelection

> A stretch of time on some tracks of an arrangement, drawn by dragging across bare lanes, with its overlay and what the keyboard does with it: copy, cut, paste, duplicate, consolidate, loop, fade, delete and open time, each one step of undo.

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

```ts
import { useTimeSelection } from "@/hooks/use-time-selection";
```

- Files: `hooks/use-time-selection.ts`, `components/audio-ui/time-selection.tsx`
- Depends on: `arrangement`, `use-arrangement`; npm: `@audio-ui/react`
- Used by: `arrangement-editor`, `arrangement-view`, `block-audio-editor`, `block-timeline`

| Export | Kind | What it is |
| --- | --- | --- |
| `UseTimeSelectionOptions` | interface |  |
| `useTimeSelection` | function | A stretch of time on some tracks, and what the keyboard does with it. |

## Usage

`useTimeSelection` is a stretch of time on some tracks and what the keyboard does with it. Tell it where a press on bare lane began, give its `onSelectionChange` to the lanes, and draw the overlay on the tracks it spans:

```tsx
import { TimelineTimeSelection } from "@/components/audio-ui/time-selection";
import { useTimeSelection } from "@/hooks/use-time-selection";

const selection = useTimeSelection({
  bar,
  clips,
  copyOf,
  dispatch,
  getPosition: () => engine.position.getSnapshot(),
  selectedIds,
  selectedTracks,
  tracks,
});

<TimelineLane
  data-track={track.id}
  onPointerDown={() => selection.pressLane(track.id)}
  onSelectionChange={selection.onSelectionChange}
>
  {selection.time?.tracks.includes(track.id) ? (
    <TimelineTimeSelection range={selection.time.range} />
  ) : null}
</TimelineLane>;
```

`handleKey` takes a key press, native or React's, and says whether it was one of its own, so a host's other keys can follow: Cmd/Ctrl + C and X copy and cut (the selected clips when no time is selected), V pastes at the cursor and I opens silence there; with a time selection, D duplicates it after itself, J makes one clip per track of it, L loops it and Delete empties it. With Shift too, X, V, D and Delete work on the time itself, on every track, and Cmd/Ctrl + Alt + F makes fades from it. Each is one step of undo.

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

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bar` | `number` |  | How long a stretch Cmd/Ctrl + I opens with nothing selected, in seconds. |
| `clips, tracks, selectedIds, selectedTracks` | `as useArrangement returns them` |  | What a selection and a paste read. |
| `copyOf, dispatch` | `(time) => Clipping, (command) => void` |  | From `useArrangement`. |
| `getPosition` | `() => number` |  | Where the cursor is, in seconds. |
| `time, setTime, clear` | `{ range, tracks } \| null, (time) => void, () => void` |  | The stretch of time selected. |
| `pressLane, onSelectionChange` | `(trackId \| null) => void, for TimelineLane` |  | A press on bare lane, and the drag from it. |
| `handleKey` | `(event) => boolean` |  | Runs the command a key asks for, and says whether there was one. |