# Plot > The headless Plot of @audio-ui/react: its parts, what each renders and owns, and their props. ```bash npm install @audio-ui/react ``` ```ts import { Plot } from "@audio-ui/react/plot"; ``` | Export | Kind | What it is | | --- | --- | --- | | `Plot.formatTick` | function | A tick as short text: 1000 as "1k", 0.5 as "0.5", -12 as "-12". | | `Plot.useValueAtPointer` | function | Turns a pointer position into a value on the plot: for adding a point where someone double-clicks, or reading out what is under the cursor. | | `Plot.Band` | function | A stretch of the plot between two values on one axis, across the whole of the other: the frequencies a sweep can reach, the levels over a threshold. | | `Plot.Cursor` | function | Follows the pointer over the plot, for crosshair lines and a readout of what is under it. | | `Plot.CursorReadout` | function | The value under the pointer, as text: `format` turns it into what to show, and the text is written straight into the DOM as the pointer moves. | | `Plot.Curve` | function | A curve across the whole plot: `y = fn(x)` in the axes' units, such as an equalizer's response in dB at each frequency. | | `Plot.Dot` | function | A point on the plot that nothing drags: where the signal is right now, such as the input level on a compressor's curve. | | `Plot.Graph` | function | The drawing surface: an `` covering the plot, stretched to its size, that `Plot.Curve`, `Plot.Line` and `Plot.Band` draw in. | | `Plot.Grid` | function | Grid lines and their labels, drawn from the axes: round values along each axis you give, so you do not place each line and label by hand. | | `Plot.Handle` | function | A point on the plot that can be moved: an equalizer band at its frequency and gain, a filter's cutoff and resonance, a compressor's threshold. | | `Plot.Line` | function | A straight line across the plot at a value: vertical at an x value, such as a filter's cutoff, or horizontal at a y value, such as 0 dB. | | `Plot.Mark` | function | A label at a value on one axis, such as "1k" under a frequency or "+12" by a gain: placed at the value along the axis and left to you to set apart from the plot's edge. | | `Plot.Root` | function | Groups the parts of a plot and owns its two axes: the range of each and how values spread along it, evenly or logarithmically, the way frequency is drawn. | | `Plot.Trace` | function | A live line across the plot: the list of y values a `source` holds, such as the spectrum of the sound, spread evenly across the x axis. | ## Anatomy Import the primitive and assemble its parts. ```tsx import { Plot } from "@audio-ui/react"; ``` ## API reference ### Root Groups the parts of a plot and owns its two axes: the range of each and how values spread along it, evenly or logarithmically, the way frequency is drawn. Everything placed on the plot (curves, lines, bands, handles) is placed in the axes' units. Renders a `
` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `disabled` | `boolean` | | | | `maxX` | `number` | `1` | | | `maxY` | `number` | `1` | | | `minX` | `number` | `0` | | | `minY` | `number` | `0` | | | `scaleX` | `Scale` | `"linear"` | How x values spread across: `"log"` for frequency, or your own `{ toPosition, toValue }`. | | `scaleY` | `Scale` | `"linear"` | How y values spread up. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Band A stretch of the plot between two values on one axis, across the whole of the other: the frequencies a sweep can reach, the levels over a threshold. Sits in `Plot.Graph`. Renders a `` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `axis` | `"x" \| "y"` | | The axis `from` and `to` are values on. | | `from` | `number` | | | | `to` | `number` | | | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Dot A point on the plot that nothing drags: where the signal is right now, such as the input level on a compressor's curve. Give it a `source` and it moves straight in the DOM without re-rendering React, or a `value` for a still point. Hidden from assistive technology and from the pointer. Renders a `
` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `source` | `DotSource` | | A live point, followed without re-rendering. Takes precedence over `value`. | | `value` | `Point` | | A still point, in the axes' units. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Cursor Follows the pointer over the plot, for crosshair lines and a readout of what is under it. It covers the plot, lets pointer events through, and sets `--plot-cursor-x` and `--plot-cursor-y` (0% to 100% across and down) and `data-active` while the pointer is over the plot with a mouse or a pen, all in the DOM without re-rendering React. Put lines in it that use the two variables, and a `Plot.CursorReadout`. Renders a `
` element. **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### CursorReadout The value under the pointer, as text: `format` turns it into what to show, and the text is written straight into the DOM as the pointer moves. It sits where the pointer is; set its offset and its look with your own classes. Renders a `
` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `format` | `(value: Point) => string` | | Turns the value under the pointer, in the axes' units, into the text shown. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Grid Grid lines and their labels, drawn from the axes: round values along each axis you give, so you do not place each line and label by hand. It covers the plot, is hidden from assistive technology and from the pointer, and marks its parts for styling: `data-part="line"` and `data-part="label"`, each with `data-axis`, and `data-zero` on the line at zero. Renders a `
` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `x` | `GridAxis` | | Grid lines across, at values on the x axis. Leave it out for none. | | `y` | `GridAxis` | | Grid lines along, at values on the y axis. Leave it out for none. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Handle A point on the plot that can be moved: an equalizer band at its frequency and gain, a filter's cutoff and resonance, a compressor's threshold. Its value is in the axes' units, and `axis` can hold it to one of them. Dragging moves it from where it is, never jumping to the pointer, four times finer with Shift. A double click, an Alt + click or the Delete key return it to `defaultValue`, or the middle of the plot. It holds a native `` per axis it moves along, carrying the accessible names: the first takes focus, and the arrow keys move it by a hundredth of the axis, a tenth with Shift. Renders a `
` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `axis` | `"both" \| Axis` | `"both"` | The axes the handle moves along; the other keeps the value given. | | `defaultValue` | `Value` | | Uncontrolled starting value. Defaults to the middle of the plot. | | `disabled` | `boolean` | | | | `getAriaLabel` | `(axis: Axis) => string` | | Names each axis input. Defaults to `aria-label`, followed by "X" / "Y" when the handle moves along both. | | `getAriaValueText` | `(value: number, axis: Axis) => string` | | Returns an axis input's `aria-valuetext`, from its value. Defaults to the number. | | `onValueChange` | `(value: Value, eventDetails: ChangeEventDetails) => void` | | Fires while the handle is moved: drag, keyboard and input changes. | | `onValueCommitted` | `(value: Value, eventDetails: CommitEventDetails) => void` | | Fires when a gesture that moved the handle ends, and after each key or input change. | | `value` | `Value` | | The handle's position, in the axes' units. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | | `data-dragging` | Whether a pointer is dragging the handle. | ### Graph The drawing surface: an `` covering the plot, stretched to its size, that `Plot.Curve`, `Plot.Line` and `Plot.Band` draw in. Strokes keep their width however the plot is stretched. Hidden from assistive technology and from the pointer. Renders a `` element. **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Trace A live line across the plot: the list of y values a `source` holds, such as the spectrum of the sound, spread evenly across the x axis. It is drawn straight in the DOM each time the source changes, without re-rendering React, so it can follow audio frame by frame. With `fillTo`, it closes down to that y value to be filled as an area. Sits in `Plot.Graph`. Renders a `` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `fillTo` | `number` | | Closes the line to this y value, so it can be filled as an area. | | `max` | `number` | | Top of the scale the values are on. Defaults to the plot's y axis. | | `min` | `number` | | Bottom of the scale the values are on. Defaults to the plot's y axis. | | `source` | `TraceSource` | | The live y values; the snapshot may be one array updated in place. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Curve A curve across the whole plot: `y = fn(x)` in the axes' units, such as an equalizer's response in dB at each frequency. With `fillTo`, it closes down to that y value, to be filled as an area. Sits in `Plot.Graph`. Renders a `` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `fillTo` | `number` | | Closes the curve to this y value, so it can be filled as an area. | | `fn` | `(x: number) => number` | | The curve: y, in the y axis' units, at each x. | | `samples` | `number` | `256` | How many points it starts from, evenly along the x axis. It adds more where the curve bends tighter than that shows, such as a corner or a knee. | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Line A straight line across the plot at a value: vertical at an x value, such as a filter's cutoff, or horizontal at a y value, such as 0 dB. Sits in `Plot.Graph`. Renders a `` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `axis` | `"x" \| "y"` | | `"x"` draws a vertical line at an x value, `"y"` a horizontal one at a y value. | | `value` | `number` | | | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ### Mark A label at a value on one axis, such as "1k" under a frequency or "+12" by a gain: placed at the value along the axis and left to you to set apart from the plot's edge. Hidden from assistive technology, which reads the handles' own values. Renders a `
` element. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `axis` | `"x" \| "y"` | | The axis `value` is on: `"x"` places it across, `"y"` down. | | `value` | `number` | | | **Data attributes** | Attribute | Description | | --- | --- | | `data-disabled` | Present when disabled. | ## Styled The registry's styled Plot, its usage and interaction: [Plot](/docs/components/base/plot).