Quick Start Guide

Get up and running with AudioUI in minutes. Learn the basics of using AudioUI components in your application.

This guide will help you get started with AudioUI by building a simple audio control interface. You'll learn the basic patterns for using AudioUI components.

Minimal Setup

First, ensure AudioUI is installed and the CSS is imported:

App.tsx
import { useState } from "react";
import { Knob } from "@cutoff/audio-ui-react";
import "@cutoff/audio-ui-react/style.css";
 
export default function App() {
  const [cutoff, setCutoff] = useState(0.5);
 
  return (
    <div>
      <Knob
        value={cutoff}
        onChange={(e) => setCutoff(e.value)}
        label="Cutoff"
      />
    </div>
  );
}

This creates a basic knob control. The value prop controls the current value, and onChange is called when the user interacts with the knob.

Basic Usage Pattern

AudioUI components follow a controlled component pattern. You manage the state in your component and pass it to AudioUI:

AudioControls.tsx
import { useState } from "react";
import { Knob, Slider } from "@cutoff/audio-ui-react";
 
export default function AudioControls() {
  const [cutoff, setCutoff] = useState(0.5);
  const [resonance, setResonance] = useState(0.3);
  const [volume, setVolume] = useState(0.7);
 
  return (
    <div style={{ display: "flex", gap: "20px", padding: "20px" }}>
      <Knob
        value={cutoff}
        onChange={(e) => setCutoff(e.value)}
        label="Cutoff"
      />
      <Knob
        value={resonance}
        onChange={(e) => setResonance(e.value)}
        label="Resonance"
      />
      <Slider
        value={volume}
        onChange={(e) => setVolume(e.value)}
        label="Volume"
        orientation="vertical"
      />
    </div>
  );
}

Working with Value Ranges

AudioUI components accept real values. When you provide min and max props, the component handles the conversion internally:

ParameterControl.tsx
import { useState } from "react";
import { Knob } from "@cutoff/audio-ui-react";
 
export default function ParameterControl() {
  const [frequency, setFrequency] = useState(1000);
 
  return (
    <Knob
      value={frequency}
      onChange={(e) => setFrequency(e.value)}
      label="Frequency"
      min={20}
      max={20000}
    />
  );
}

The onChange event provides the value in the range you specified. AudioUI handles the normalization internally.

Using Buttons

Buttons support both toggle (latch) and momentary modes:

ButtonExample.tsx
import { useState } from "react";
import { Button } from "@cutoff/audio-ui-react";
 
export default function ButtonExample() {
  const [isOn, setIsOn] = useState(false);
  const [isPressed, setIsPressed] = useState(false);
 
  return (
    <div style={{ display: "flex", gap: "10px" }}>
      <Button
        label="Power"
        latch={true}
        value={isOn}
        onChange={(e) => setIsOn(e.value)}
      />
      <Button
        label="Record"
        latch={false}
        value={isPressed}
        onChange={(e) => setIsPressed(e.value)}
      />
    </div>
  );
}

Combining Components

Here's a complete example combining multiple components:

SynthesizerPanel.tsx
import { useState } from "react";
import { Knob, Slider, Button } from "@cutoff/audio-ui-react";
 
export default function SynthesizerPanel() {
  const [cutoff, setCutoff] = useState(0.5);
  const [resonance, setResonance] = useState(0.3);
  const [volume, setVolume] = useState(0.7);
  const [isActive, setIsActive] = useState(true);
 
  return (
    <div style={{ display: "flex", gap: "20px", padding: "20px" }}>
      <Button
        label="Power"
        latch={true}
        value={isActive}
        onChange={(e) => setIsActive(e.value)}
      />
      <Knob
        value={cutoff}
        onChange={(e) => setCutoff(e.value)}
        label="Cutoff"
        min={20}
        max={20000}
      />
      <Knob
        value={resonance}
        onChange={(e) => setResonance(e.value)}
        label="Resonance"
        min={0}
        max={100}
      />
      <Slider
        value={volume}
        onChange={(e) => setVolume(e.value)}
        label="Volume"
        orientation="vertical"
        min={0}
        max={100}
      />
    </div>
  );
}

Next Steps

Now that you understand the basics: