# fader

> The fader's controller from @audio-ui/core: a bounded value on a straight travel, dragged, stepped, scrolled, typed and reset, the same whatever draws it.

```bash
npm install @audio-ui/core
```

```ts
import { createFaderController, faderShare, DEFAULT_MAX, DEFAULT_MIN, WHEEL_DELTA_EPSILON } from "@audio-ui/core/fader";
```

- Adapters: `@audio-ui/react/fader`, `@audio-ui/elements/fader`

| Export | Kind | What it is |
| --- | --- | --- |
| `createFaderController` | function | A fader's behavior with no view attached: its value, held or controlled, every way of changing it, and what it looks like as a snapshot. |
| `FaderChangeEventDetails` | type | What `onValueChange` receives with each change: the reason, the event behind it, and `cancel()` to refuse the change. |
| `FaderChangeEventReason` | type | Why the value changed: `"drag"`, `"track-press"`, `"keyboard"`, `"wheel"`, `"input-change"` (a typed value) or `"reset"`. |
| `FaderCommitEventDetails` | type | What `onValueCommitted` receives once a gesture ends: the reason and the event behind it. |
| `FaderCommitEventReason` | type | Why the value was committed: the same reasons as a change. |
| `FaderController` | interface | What `createFaderController` returns: the snapshot to draw from, and the press, keys, wheel, typed value and reset that change it. |
| `FaderOptions` | interface | The options of `createFaderController`: the value, held or controlled, its range, steps, anchor and orientation, its formatting and the callbacks. |
| `FaderOrientation` | type | Which way a fader's travel runs. |
| `FaderSnapshot` | interface | What a view draws a fader from. |
| `faderShare` | function | The share of the travel `value` sits at, 0…100. |
| `DEFAULT_MAX` | const | The top of a fader's range unless given: 6. |
| `DEFAULT_MIN` | const | The bottom of a fader's range unless given: -60, as for a level in dB. |
| `WHEEL_DELTA_EPSILON` | const | A wheel movement smaller than this is ignored. |

## Usage

The controller follows the [contract](/docs/core/controllers) every controller shares: create it once, draw from its snapshot, send it the input.

```ts
import { createFaderController } from "@audio-ui/core/fader";

const fader = createFaderController({ min: -60, max: 6, value: -12, step: 0.5, orientation: "vertical" });
const unsubscribe = fader.subscribe(() => draw(fader.getSnapshot()));
control.addEventListener("pointerdown", (event) => fader.press(event, control, thumb));
control.addEventListener("keydown", (event) => { if (fader.keyDown(event, control)) event.preventDefault(); });
const detach = fader.attachWheel(control);
```

| Option | Meaning |
| --- | --- |
| `value`, `defaultValue` | The controlled value, or the uncontrolled start and what a reset returns to |
| `min`, `max`, `step`, `largeStep` | The range (-60 to 6 unless given), the grid, and the step that Shift takes |
| `anchor` | The value the fill starts from, for a fader that is centred on a value |
| `orientation` | `"horizontal"` or `"vertical"` |
| `format`, `locale` | `Intl.NumberFormat` options for `formatted` |
| `disabled` | Takes every input away |

`press(event, control, thumb)` takes the thumb too: a press on the thumb keeps the pointer where it grabbed the thumb, so the value does not jump to the pointer. `reset(event)` returns the value to its default: the element calls it on a double-click (listen for `dblclick` on the control), on Alt with a press, and on Delete or Backspace. A double tap on touch is not a reset for a fader, as it is for a knob: a tap on a fader's track sets the value, so two quick taps are two values.

`faderShare(value, min, max)` is where a value sits along the travel, from 0 to 100, for a view that places the thumb itself.

**In React**

The [Fader](/docs/components/base/fader) draws this controller in React.

**In Vue, Svelte and Web**

[`<audio-ui-fader>`](/docs/elements/fader) draws this controller in your framework.