Plot

The headless Plot of @audio-ui/react: its parts, what each renders and owns, and their props.


pnpm add @audio-ui/react

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 `<svg>` 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.

import { Plot } from "@audio-ui/react";

<Plot.Root>
  <Plot.Grid />
  <Plot.Graph>
    <Plot.Curve />
    <Plot.Trace />
    <Plot.Line />
    <Plot.Band />
  </Plot.Graph>
  <Plot.Mark />
  <Plot.Dot />
  <Plot.Cursor>
    <Plot.CursorReadout />
  </Plot.Cursor>
  <Plot.Handle />
</Plot.Root>

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 <div> element.

Props · 7

Data attributes · 1

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 <rect> element.

Props · 3

Data attributes · 1

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 <div> element.

Props · 2

Data attributes · 1

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 <div> element.

Data attributes · 1

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 <div> element.

Props · 1

Data attributes · 1

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 <div> element.

Props · 2

Data attributes · 1

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 <input type="range"> 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 <div> element.

Props · 8

Data attributes · 2

data-disabled

Present when disabled.

data-dragging

Whether a pointer is dragging the handle.

Graph

The drawing surface: an <svg> 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 <svg> element.

Data attributes · 1

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 <path> element.

Props · 4

Data attributes · 1

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 <path> element.

Props · 3

Data attributes · 1

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 <line> element.

Props · 2

Data attributes · 1

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 <div> element.

Props · 2

Data attributes · 1

data-disabled

Present when disabled.

Styled

The registry's styled Plot, its usage and interaction: Plot.

Envelope Piano

Built by Ouest Labs, the source code is available on GitHub.

RSS