Lab

First Component

Add a knob to your app and style its state.

Let's add a Cutoff knob. Drag it, turn the mouse wheel over it or use the arrow keys, and its value follows.

If you haven't installed the primitive yet, start with Installation.

Create the component

Create CutoffKnob.tsx next to your app component. The knob keeps its value in your state, and its parts are placed inside its Root:

CutoffKnob.tsx
import { useState } from "react";
import { Knob } from "@/components/audio-ui/knob/react";
import "./cutoff-knob.css";

export function CutoffKnob() {
  const [value, setValue] = useState(40);
  return (
    <Knob.Root
      format={{ style: "unit", unit: "percent" }}
      onValueChange={setValue}
      value={value}
    >
      <Knob.Control className="cutoff-control">
        <Knob.Track className="cutoff-track" />
        <Knob.Indicator className="cutoff-arc" />
        <Knob.Thumb aria-label="Cutoff" className="cutoff-thumb" />
      </Knob.Control>
      <Knob.Value />
    </Knob.Root>
  );
}

The Root owns the value. The Control takes the pointer and the wheel. The Track and the Indicator draw the two arcs, the Thumb is the focusable input and turns with the value, and the Value writes the text. Each part takes the classes of its element.

Use it in your app

In your app component, import and render CutoffKnob:

App.tsx
import { CutoffKnob } from "./CutoffKnob";

export default function App() {
  return <CutoffKnob />;
}

Open your app. You should see a ring and a value, "40 %". It has no look yet: add styles to see its arcs.

Add styles

The knob is headless: it brings behavior and accessibility, and no styles. Save this as cutoff-knob.css, next to the component:

cutoff-knob.css
.cutoff-control {
  position: relative;
  display: block;
  width: 6rem;
  height: 6rem;
  cursor: grab;
  touch-action: none;
}

.cutoff-control[data-dragging] {
  cursor: grabbing;
}

.cutoff-track,
.cutoff-arc {
  position: absolute;
  inset: 0;
}

.cutoff-track {
  color: #d4d4d4;
}

.cutoff-arc {
  color: #2f7d4a;
}

.cutoff-thumb {
  position: absolute;
  inset: 0.75rem;
  border-radius: 9999px;
  background: #fff;
  box-shadow: 0 0 0 1px #d4d4d4;
}

.cutoff-thumb::after {
  content: "";
  position: absolute;
  top: 0.4rem;
  left: 50%;
  width: 2px;
  height: 0.6rem;
  margin-left: -1px;
  border-radius: 1px;
  background: #111;
}

.cutoff-control[data-dragging] .cutoff-thumb {
  box-shadow: 0 0 0 2px #2f7d4a;
}

The two arcs take their color from the CSS color of their part. While the knob is dragged, its Control has a data-dragging attribute, which the last two rules use. Each part carries state attributes like it (data-disabled, data-drag-mode), and the page of the Knob lists them.

With Tailwind CSS, put the classes on the parts instead, with the data-dragging: variant: data-dragging:cursor-grabbing.

Try it

Drag around the ring, turn the mouse wheel over it, or focus it with Tab and press the arrow keys, Page Up, Page Down, Home and End. A screen reader announces it as a slider named "Cutoff", with its value, because the Thumb holds a native <input type="range">.

Continue with the page of the Knob for its options: a log scale for a frequency, marks around the dial, and the details of every change.

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