--- # Introduction # Introduction > Overview of AudioUI, a React component library for building audio and MIDI application interfaces. AudioUI is a React component library designed for building user interfaces in audio and MIDI applications. It provides a set of components optimized for the performance and interaction patterns required by music software, digital audio workstations (DAWs), audio plugins with web UIs, and other audio-centric applications. > **Want to jump in?:** If you prefer to go straight to the point or like exploring by doing, head over to the [Playground app](https://playground.cutoff.dev). It showcases AudioUI capabilities and contains many examples you can try live. ## Design Philosophy AudioUI is built around core principles that address the unique challenges of audio software development: ### Performance First Audio applications have strict performance requirements. Components are optimized for minimal re-renders and low-latency interactions to ensure the UI remains responsive, even under heavy load. ### Hybrid Architecture The library provides both opinionated components for rapid development and non-opinionated primitives for deep customization: * **Opinionated Components**: Ready-to-use components like Knob, Slider, Button, CycleButton, and Keys with carefully designed APIs, multiple visual variants, and sensible defaults. These components are based on thorough observation of existing audio apps and plugins, built with the intent of covering 90% of the needs of most audio app and plugin developers. They are themable using a ThemeManager, can be fine-tuned using styles and props, and provide several variants per component to match different visual styles. * **Non-Opinionated Components**: Generic control components, SVG primitives, and base building blocks that enable full customization. Ideal for creating unique visual designs that match your brand or existing plugin aesthetics. The [customization page](https://playground.cutoff.dev/examples/customization) contains multiple examples of totally customized components built with these primitives, and its source code is available for reference. ### Universal Access AudioUI is designed from the ground up to be fully accessible with ARIA support and keyboard navigation, and mobile-ready with responsive, touch-optimized interactions. ### Developer Experience The library is written entirely in TypeScript for type safety and provides a flexible theming system through a ThemeManager. The theme system currently allows you to define a primary color and a roundness attribute, with more theme options planned for the 1.0 release (including glowness, reflectiveness, and more). For an overview of theming on vector components, see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features) in the Vector introduction. The architecture separates framework-agnostic core logic from React-specific implementations, enabling potential support for other frameworks in the future. ## Project Status **Developer Preview** — AudioUI is currently in active development. The core components and APIs are functional and ready for use, but the library is still evolving. **Current Status:** * Core component APIs (Knob, Slider, Button, CycleButton, Keys) are stable and production-ready * Comprehensive audio parameters model with support for Continuous, Discrete, and Boolean controls * Generic film strip and bitmap image components for each type of audio parameter * Comprehensive interaction system for each type of parameter (drag, wheel, keyboard) * Layout system with adaptive sizing * Theming and customization system with SVG primitives and base components * Built-in support for dark and light mode * Ready for mobile devices (responsive, touch ready) **In Progress:** * Additional visual variants for CycleButton and Button (Knob and Slider already have multiple variants available) * Size system improvements * Documentation expansion **Planned for 1.0:** * Additional components: XY Pad, Pitch/Mod Wheels and Levers, and an Icon library dedicated to audio and MIDI apps and plugins * Enhanced theme system with glowness, reflectiveness, and more visual attributes As a Developer Preview release, breaking changes may occur as we refine the API and architecture. We recommend pinning to specific versions for production use. ## Core Components AudioUI provides a range of components essential for building audio applications: ### Built-in Controls * **Knob**: A versatile rotary knob for parameter control with multiple visual variants (abstract, simplest, plainCap, iconCap) * **Slider**: A linear slider for horizontal or vertical adjustments with multiple visual variants (abstract, trackless, trackfull, stripless) * **Button**: A customizable button with styles suited for audio interfaces, supporting both toggle and momentary modes. Additional variants coming in future releases. * **CycleButton**: A discrete control for cycling through a set of options with multiple visual variants. Additional variants coming in future releases. ### Device Components * **Keys**: A responsive and interactive piano keyboard component ### Raster Components * **FilmStrip Controls**: Bitmap sprite sheet-based controls for industry-standard control representation * **Image-Based Controls**: Image-based knobs and switches for custom visual designs ### Primitives * **Control Primitives**: Low-level control components for building custom controls * **SVG Primitives**: SVG view primitives for composing custom radial and linear controls ## Architecture AudioUI is organized as a monorepo with a clear separation between framework-agnostic core logic and framework-specific implementations: * **`@cutoff/audio-ui-core`**: Framework-agnostic package containing all business logic, models, controllers, utilities, and styles. Can be used by any framework implementation or in non-framework contexts. * **`@cutoff/audio-ui-react`**: The React component library implementation, published to npm. Provides React components, hooks, and React-specific adapters that wrap the framework-agnostic core. This architecture enables potential implementations for other frameworks (Solid, Vue, etc.) that would share the same core logic. ## Resources * **Playground**: Try AudioUI components live, explore examples, and see customization patterns at [playground.cutoff.dev](https://playground.cutoff.dev). The playground source code is available and contains multiple examples, including a dedicated [customization page](https://playground.cutoff.dev/examples/customization) with totally customized components built with AudioUI primitives. * **Community**: Join our [Discord server](https://discord.gg/7RB6t2xqYW) for discussions, general questions, and support. Discussions are preferred in Discord channels (general, support, etc.). * **Support**: Create support issues in the [GitHub repository Issues](https://github.com/cutoff/audio-ui/issues) * **Wishlist**: A dedicated wishlist channel is available in the Cutoff Discord, allowing you to create feature requests and vote for the most wanted features * **Repository**: [GitHub](https://github.com/cutoff/audio-ui) ## Next Steps Ready to get started? Check out the [Installation](https://cutoff.dev/audio-ui/docs/latest/getting-started/installation) guide to set up AudioUI in your project, or jump to the [Quick Start Guide](https://cutoff.dev/audio-ui/docs/latest/getting-started/quick-start-guide) for a hands-on introduction. --- # Installation # Installation > Install AudioUI in your project. Choose your framework for framework-specific setup instructions. This guide covers the general installation process for AudioUI. For framework-specific setup instructions, see the framework installation pages linked below. ## Prerequisites Before installing AudioUI, ensure you have: * **Node.js** 18.0 or higher * **React** 18.2.0 or higher (peer dependency) * A package manager: `pnpm`, `npm`, `yarn`, or `bun` ## Installation Steps ### Install Peer Dependencies AudioUI requires React and React DOM as peer dependencies. Install them first: #### pnpm ```bash pnpm add react@^19.0.0 react-dom@^19.0.0 ``` #### npm ```bash npm install react@^19.0.0 react-dom@^19.0.0 ``` #### yarn ```bash yarn add react@^19.0.0 react-dom@^19.0.0 ``` #### bun ```bash bun add react@^19.0.0 react-dom@^19.0.0 ``` ### Install the Package Install AudioUI using your preferred package manager: #### pnpm ```bash pnpm add @cutoff/audio-ui-react ``` #### npm ```bash npm install @cutoff/audio-ui-react ``` #### yarn ```bash yarn add @cutoff/audio-ui-react ``` #### bun ```bash bun add @cutoff/audio-ui-react ``` ### Import the CSS Import the AudioUI stylesheet in your application's entry point (e.g., `main.tsx`, `App.tsx`, or `_app.tsx`): ```tsx import "@cutoff/audio-ui-react/style.css"; ``` This import must be included for components to render correctly. ### Verify Installation Create a simple test component to verify everything is working: ```tsx import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function TestComponent() { const [value, setValue] = useState(0.5); return setValue(e.value)} label="Test" />; } ``` If the component renders without errors, installation is successful. ## Framework-Specific Installation For detailed setup instructions tailored to your framework, see: * [Vite](https://cutoff.dev/audio-ui/docs/latest/getting-started/installation/vite) - Fast build tool and dev server * [Next.js](https://cutoff.dev/audio-ui/docs/latest/getting-started/installation/nextjs) - React framework for production * [Tauri](https://cutoff.dev/audio-ui/docs/latest/getting-started/installation/tauri) - Build desktop applications with web technologies - Build desktop applications with web technologies ## Package Information * **Package name**: `@cutoff/audio-ui-react` * **Current version**: `latest` (Developer Preview) * **License**: GPL-3.0-only (open source) or Commercial license available ## Next Steps Once installation is complete, check out the [Quick Start Guide](https://cutoff.dev/audio-ui/docs/latest/getting-started/quick-start-guide) to learn how to use AudioUI components in your application. --- # Vite # Vite > Install and set up AudioUI in a Vite project. Vite provides fast development and optimized production builds. This guide covers installing AudioUI in a Vite project. Vite is a fast build tool and development server that's ideal for React applications. ## Prerequisites * Node.js 18.0 or higher * Basic familiarity with React and Vite ## Installation Steps ### Create a Vite Project If you don't have a Vite project yet, create one: #### pnpm ```bash pnpm create vite my-audio-app --template react-ts cd my-audio-app pnpm install ``` #### npm ```bash npm create vite@latest my-audio-app -- --template react-ts cd my-audio-app npm install ``` #### yarn ```bash yarn create vite my-audio-app --template react-ts cd my-audio-app yarn install ``` #### bun ```bash bun create vite my-audio-app --template react-ts cd my-audio-app bun install ``` This creates a new Vite project with React and TypeScript. ### Install AudioUI Install AudioUI using your package manager: #### pnpm ```bash pnpm add @cutoff/audio-ui-react ``` #### npm ```bash npm install @cutoff/audio-ui-react ``` #### yarn ```bash yarn add @cutoff/audio-ui-react ``` #### bun ```bash bun add @cutoff/audio-ui-react ``` ### Import CSS Import the AudioUI stylesheet in your css file. In a Vite project, this is typically `src/index.css`: ```tsx title="src/index.css" showLineNumbers @import url("@cutoff/audio-ui-react/style.css"); // Rest of the styles... ``` ### Create Your First Component Create a simple component to test AudioUI: ```tsx title="src/App.tsx" showLineNumbers import { useState } from "react"; import './App.css' import { Knob } from "@cutoff/audio-ui-react"; export default function App() { const [value, setValue] = useState(0.5); return ( setValue(e.value)} label="Cutoff" size="large" /> ); } ``` ### Start Development Server Start the Vite development server: #### pnpm ```bash pnpm dev ``` #### npm ```bash npm dev ``` #### yarn ```bash yarn dev ``` #### bun ```bash bun run dev ``` Open your browser to the URL shown in the terminal (typically `http://localhost:5173`). You should see your AudioUI component rendering. ## Configuration Vite works with AudioUI out of the box. No additional configuration is required. The CSS import is handled automatically by Vite's CSS processing. ## Building for Production Build your application for production: ### pnpm ```bash pnpm build ``` ### npm ```bash npm build ``` ### yarn ```bash yarn build ``` ### bun ```bash bun run build ``` The optimized build will be in the `dist` directory. AudioUI styles are automatically included in the build. ## Next Steps * Check out the [Quick Start Guide](https://cutoff.dev/audio-ui/docs/latest/getting-started/quick-start-guide) to learn more about using AudioUI components * Explore [Code Examples](https://cutoff.dev/audio-ui/docs/latest/getting-started/code-examples) for practical usage patterns * Read the [Component Documentation](https://cutoff.dev/audio-ui/docs/latest/components) for detailed API references --- # Next.js # Next.js > Install and set up AudioUI in a Next.js project using the App Router. This guide covers installing AudioUI in a Next.js project using the App Router (Next.js 13+). Next.js is a React framework optimized for production. ## Prerequisites * Node.js 18.0 or higher * Next.js 13.0 or higher (App Router) * Basic familiarity with React and Next.js ## Installation Steps ### Create a Next.js Project If you don't have a Next.js project yet, create one: #### pnpm ```bash pnpm create next-app@latest my-audio-app cd my-audio-app ``` #### npm ```bash npx create-next-app@latest my-audio-app cd my-audio-app ``` #### yarn ```bash yarn create next-app@latest my-audio-app cd my-audio-app ``` #### bun ```bash bunx create-next-app@latest my-audio-app cd my-audio-app ``` When prompted, choose: * TypeScript: Yes * App Router: Yes * Other options as needed ### Install AudioUI Install AudioUI using your package manager: #### pnpm ```bash pnpm add @cutoff/audio-ui-react ``` #### npm ```bash npm install @cutoff/audio-ui-react ``` #### yarn ```bash yarn add @cutoff/audio-ui-react ``` #### bun ```bash bun add @cutoff/audio-ui-react ``` ### Import CSS Import the AudioUI stylesheet in your root stylsheet. In Next.js, this is `app/globals.css`: ```tsx title="app/globals.css" showLineNumbers @import url("@cutoff/audio-ui-react/style.css"); // Rest of your styles... ``` ### Create a Client Component AudioUI components are client components. Create a client component for your audio controls: ```tsx title="components/AudioControls.tsx" showLineNumbers "use client"; import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function AudioControls() { const [value, setValue] = useState(0.5); return ( setValue(e.value)} label="Cutoff" size="large" /> ); } ``` ### Use in a Page Use your component in a page: ```tsx title="app/page.tsx" showLineNumbers import AudioControls from "../components/AudioControls"; export default function Home() { return (

My Audio App

); } ``` ### Start Development Server Start the Next.js development server: #### pnpm ```bash pnpm run dev ``` #### npm ```bash npm run dev ``` #### yarn ```bash yarn dev ``` #### bun ```bash bun run dev ``` Open your browser to `http://localhost:3000`. You should see your AudioUI component rendering. ## Important Notes ### Client Components All AudioUI components must be used in client components. Always include the `"use client"` directive at the top of files that use AudioUI components. ### Server Components If you need to use AudioUI components in a server component, create a separate client component wrapper: ```tsx title="app/components/AudioPanel.tsx" showLineNumbers "use client"; import { Knob, Slider } from "@cutoff/audio-ui-react"; // ... component implementation ``` Then import and use it in your server component. ## Building for Production Build your application for production: ### pnpm ```bash pnpm run build ``` ### npm ```bash npm run build ``` ### yarn ```bash yarn build ``` ### bun ```bash bun run build ``` AudioUI styles are automatically included in the Next.js build output. ## Next Steps * Check out the [Quick Start Guide](https://cutoff.dev/audio-ui/docs/latest/getting-started/quick-start-guide) to learn more about using AudioUI components * Explore [Code Examples](https://cutoff.dev/audio-ui/docs/latest/getting-started/code-examples) for practical usage patterns * Read the [Component Documentation](https://cutoff.dev/audio-ui/docs/latest/components) for detailed API references --- # Tauri # Tauri > Install and set up AudioUI in a Tauri application for building desktop audio applications. This guide covers installing AudioUI in a Tauri application. Tauri allows you to build desktop applications using web technologies, making it ideal for audio applications that need native desktop performance. ## Prerequisites * Node.js 18.0 or higher * Rust (for Tauri backend) * Basic familiarity with React and Tauri ## Installation Steps ### Create a Tauri Project If you don't have a Tauri project yet, create one. You can use either interactive or non-interactive setup: **Interactive setup:** #### pnpm ```bash pnpm create tauri-app@latest ``` #### npm ```bash npm create tauri-app@latest ``` #### yarn ```bash yarn create tauri-app ``` #### bun ```bash bun create tauri-app ``` When prompted: * Choose your package manager (npm, pnpm, yarn, bun) * Choose "React" as the UI framework * Choose "TypeScript" if you want TypeScript support **Non-interactive setup:** You can skip prompts by using CLI flags: #### pnpm ```bash npx create-tauri-app@latest tauri-project \ --manager pnpm \ --template react-ts \ --yes ``` #### npm ```bash npx create-tauri-app@latest tauri-project \ --manager npm \ --template react-ts \ --yes ``` #### yarn ```bash npx create-tauri-app@latest tauri-project \ --manager yarn \ --template react-ts \ --yes ``` #### bun ```bash npx create-tauri-app@latest tauri-project \ --manager bun \ --template react-ts \ --yes ``` This creates a new Tauri project with React and TypeScript. ### Install AudioUI Navigate to your project directory and install AudioUI: #### pnpm ```bash cd my-tauri-app pnpm add @cutoff/audio-ui-react ``` #### npm ```bash cd my-tauri-app npm install @cutoff/audio-ui-react ``` #### yarn ```bash cd my-tauri-app yarn add @cutoff/audio-ui-react ``` #### bun ```bash cd my-tauri-app bun add @cutoff/audio-ui-react ``` ### Import CSS Import the AudioUI stylesheet in your main css file. In a Tauri React project, this is typically `src/App.css`: ```tsx title="src/App.css" showLineNumber @import url("@cutoff/audio-ui-react/style.css"); // Rest of the styles ``` ### Create Your First Component Create a simple component to test AudioUI: ```tsx title="src/App.tsx" showLineNumbers import { useState } from "react"; import "./App.css"; import { Knob } from "@cutoff/audio-ui-react"; export default function App() { const [value, setValue] = useState(0.5); return (

My Tauri Audio App

setValue(e.value)} label="Cutoff" size="large" />
); } ``` ### Start Development Start the Tauri development server: #### pnpm ```bash pnpm tauri dev ``` #### npm ```bash npm tauri dev ``` #### yarn ```bash yarn tauri dev ``` #### bun ```bash bun run tauri dev ``` This will: 1. Start the Vite dev server for the frontend 2. Compile the Rust backend 3. Open a native window with your application You should see your AudioUI component rendering in the Tauri window. ## Building for Production Build your Tauri application for production: ### pnpm ```bash pnpm tauri build ``` ### npm ```bash npm tauri build ``` ### yarn ```bash yarn tauri build ``` ### bun ```bash bun run tauri build ``` This creates platform-specific installers (`.dmg` on macOS, `.exe` on Windows, `.AppImage` on Linux) in `src-tauri/target/release/bundle/`. ## Next Steps * Check out the [Quick Start Guide](https://cutoff.dev/audio-ui/docs/latest/getting-started/quick-start-guide) to learn more about using AudioUI components * Explore [Code Examples](https://cutoff.dev/audio-ui/docs/latest/getting-started/code-examples) for practical usage patterns * Read the [Component Documentation](https://cutoff.dev/audio-ui/docs/latest/components) for detailed API references * Learn about [Tauri commands](https://tauri.app/v1/guides/features/command) for native functionality --- # Quick Start Guide # 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: ```tsx title="App.tsx" showLineNumbers 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 (
setCutoff(e.value)} label="Cutoff" />
); } ``` 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: ```tsx title="AudioControls.tsx" showLineNumbers {1-25} 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 (
setCutoff(e.value)} label="Cutoff" /> setResonance(e.value)} label="Resonance" /> setVolume(e.value)} label="Volume" orientation="vertical" />
); } ``` ## Working with Value Ranges AudioUI components accept real values. When you provide `min` and `max` props, the component handles the conversion internally: ```tsx title="ParameterControl.tsx" showLineNumbers {8-15} import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function ParameterControl() { const [frequency, setFrequency] = useState(1000); return ( 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: ```tsx title="ButtonExample.tsx" showLineNumbers 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 (
); } ``` ## Combining Components Here's a complete example combining multiple components: ```tsx title="SynthesizerPanel.tsx" showLineNumbers 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 (
); } ``` ## Next Steps Now that you understand the basics: * Explore [Code Examples](https://cutoff.dev/audio-ui/docs/latest/getting-started/code-examples) for more component usage patterns * Check out individual [Component Documentation](https://cutoff.dev/audio-ui/docs/latest/components) for detailed API references * Learn about [theming and customization](https://cutoff.dev/audio-ui/docs/latest/getting-started/code-examples) to match your application's design --- # Code Examples # Code Examples > Practical code examples for AudioUI components. Copy and paste these examples to get started quickly. This page provides working code examples for AudioUI components. Each example is complete and ready to use in your project. ## Basic Components ### knob ```tsx title="KnobExample.tsx" showLineNumbers import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function KnobExample() { const [value, setValue] = useState(0.5); return ( setValue(e.value)} label="Cutoff" min={20} max={20000} /> ); } ``` ### slider ```tsx title="SliderExample.tsx" showLineNumbers import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderExample() { const [verticalValue, setVerticalValue] = useState(0.7); const [horizontalValue, setHorizontalValue] = useState(0.5); return (
setVerticalValue(e.value)} label="Volume" orientation="vertical" min={0} max={100} /> setHorizontalValue(e.value)} label="Pan" orientation="horizontal" min={-100} max={100} />
); } ``` ### button ```tsx title="ButtonExample.tsx" showLineNumbers 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 (
); } ``` ### cycle ```tsx title="CycleButtonExample.tsx" showLineNumbers import { useState } from "react"; import { CycleButton, OptionView } from "@cutoff/audio-ui-react"; export default function CycleButtonExample() { const [waveform, setWaveform] = useState("sine"); return ( setWaveform(e.value)} label="Waveform" > Sine Square Saw Tri ); } ``` ## Keys Component The Keys component provides an interactive piano keyboard: ```tsx title="KeysExample.tsx" showLineNumbers import { useState } from "react"; import { Keys } from "@cutoff/audio-ui-react"; export default function KeysExample() { const [notesOn, setNotesOn] = useState<(string | number)[]>([]); const handleChange = (e: { value: { note: number; active: boolean } }) => { const noteNum = e.value.note; if (e.value.active) { setNotesOn((prev) => [...prev, noteNum]); console.log("Note on:", noteNum); } else { setNotesOn((prev) => prev.filter((n) => n !== noteNum)); console.log("Note off:", noteNum); } }; return ( ); } ``` ## Combining Multiple Components Here's a complete synthesizer panel example: ```tsx title="SynthesizerPanel.tsx" showLineNumbers import { useState } from "react"; import { Knob, Slider, Button, CycleButton, OptionView, } 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); const [waveform, setWaveform] = useState("sine"); return (
); } ``` ## Using Value Formatters AudioUI provides formatters for common audio parameter displays: ```tsx title="FormatterExample.tsx" showLineNumbers import { useState } from "react"; import { Knob, frequencyFormatter, percentageFormatter, } from "@cutoff/audio-ui-react"; export default function FormatterExample() { const [frequency, setFrequency] = useState(1000); const [mix, setMix] = useState(50); return (
setFrequency(e.value)} label="Frequency" min={20} max={20000} valueFormatter={(value) => frequencyFormatter(value)} /> setMix(e.value)} label="Mix" min={0} max={100} valueFormatter={(value, paramDef) => { return percentageFormatter(value, paramDef.min, paramDef.max); }} />
); } ``` ## Theming AudioUI supports theming through the ThemeManager. You can customize the primary color and roundness attribute: ```tsx title="ThemedExample.tsx" showLineNumbers import { useState, useEffect } from "react"; import { Knob, setThemeColor, setThemeRoundness } from "@cutoff/audio-ui-react"; export default function ThemedExample() { const [value, setValue] = useState(0.5); // Set theme (runs once, affects all components) useEffect(() => { setThemeColor("#3b82f6"); // Blue accent setThemeRoundness(0.3); // Slightly rounded }, []); return ( setValue(e.value)} label="Themed Knob" /> ); } ``` The theme system currently supports primary color and roundness. For an overview of theming on vector components, see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features) in the Vector introduction. Additional theme options (glowness, reflectiveness, and more) are planned for the 1.0 release. ## Dark and Light Mode AudioUI components automatically adapt to dark and light themes based on your application's theme system. The components use CSS variables that respond to the `prefers-color-scheme` media query or your theme provider. To control the theme in your example apps: ### Using CSS You can control the theme by setting the `color-scheme` CSS property or using a class: ```tsx title="App.tsx" showLineNumbers import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; import "@cutoff/audio-ui-react/style.css"; export default function App() { const [value, setValue] = useState(0.5); const [isDark, setIsDark] = useState(false); return (
setValue(e.value)} label="Cutoff" />
); } ``` ### Using a Theme Provider If you're using a theme provider (like `next-themes` or a custom solution), AudioUI components will automatically adapt: ```tsx title="App.tsx" showLineNumbers import { useState } from "react"; import { useTheme } from "next-themes"; import { Knob } from "@cutoff/audio-ui-react"; import "@cutoff/audio-ui-react/style.css"; export default function App() { const { theme, setTheme } = useTheme(); const [value, setValue] = useState(0.5); return (
setValue(e.value)} label="Cutoff" />
); } ``` The components will automatically update their appearance when the theme changes, ensuring proper contrast and visibility in both light and dark modes. ## Component Variants AudioUI components support multiple visual variants. Here are examples using different variants: ```tsx title="VariantsExample.tsx" showLineNumbers import { useState } from "react"; import { Knob, Slider } from "@cutoff/audio-ui-react"; export default function VariantsExample() { const [value1, setValue1] = useState(0.5); const [value2, setValue2] = useState(0.5); const [value3, setValue3] = useState(0.5); return (
setValue1(e.value)} label="Abstract" variant="abstract" /> setValue2(e.value)} label="PlainCap" variant="plainCap" /> setValue3(e.value)} label="Trackless" variant="trackless" orientation="vertical" />
); } ``` Knob supports variants: `abstract`, `simplest`, `plainCap`, `iconCap`. Slider supports variants: `abstract`, `trackless`, `trackfull`, `stripless`. Additional variants for CycleButton and Button are coming in future releases. ## Next Steps * Explore individual [Component Documentation](https://cutoff.dev/audio-ui/docs/latest/components) for detailed API references * Learn about [advanced patterns](https://cutoff.dev/audio-ui/docs/latest/getting-started/quick-start-guide) and customization options * Check out the [FAQ](https://cutoff.dev/audio-ui/docs/latest/getting-started/faq) for common questions --- # Components # Components > An overview of AudioUI components—what they are, how they are organized, and how to choose the right type for your project. AudioUI provides ready-to-use controls (knobs, sliders, buttons, cycle buttons, piano keys), bitmap-based controls that use your own assets (film strips and image knobs/switches), and primitives for fully custom controls. For design philosophy and performance priorities, see the [Introduction](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction). For more context on each type before diving into individual components, see the [Vector introduction](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction) and [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). Components fall into four types: **Vector Components**, **Raster Components**, **Control Primitives**, and **View Primitives**. The table below compares these types on several criteria so you can see how they differ and choose the right one. ## Comparing the four component types Each column is one component type and links to its documentation. The rows are comparison criteria (attributes): * **Opinionated**: Fixed look-and-feel choices vs full control over appearance (you supply or compose the view). * **Themable (built-in)**: Whether the component type supports the built-in theme system (ThemeManager, color, roundness). * **Resolution-independent scaling**: Whether the visual scales without pixelation (SVG) or may pixelate when scaled (bitmap). View primitives are mostly resolution-independent but not always (e.g. bitmap used in a compound view). * **Default view**: Whether the component type provides ready-to-use visuals without supplying assets. * **Optimization responsibility**: Who is responsible for performance and optimization. For view primitives: user for compound views; the primitives themselves are framework-optimized. * **Dark/light variants**: Built-in theme support for light and dark mode; or (raster) props to supply separate dark and light assets with transition managed by the component; or user responsibility / N/A. * **Completeness**: Whether the component type is considered complete or will receive new components, variants, or primitives over time. \| Attribute | [Vector Components](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction) | [Raster Components](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction) | [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) | [View Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-customization/view-system-view-primitives) | \| --------- | ----------------- | -------------------- | ------------------ | ------------------- | \| Opinionated | Yes | No | No | No | \| Themable (built-in) | Yes | No | No | No | \| Resolution-independent scaling | Yes | No (may pixelate) | Depends on view | Mostly | \| Default view | Yes | No (requires assets) | No | No | \| Optimization responsibility | Framework | Framework | User | User (compound views); primitives framework-optimized | \| Dark/light variants | Built-in | Yes (dark/light assets) | N/A | User responsibility | \| Completeness | Will expand (components, variants, theming) | Complete | Complete (parameter model complete) | May expand (new primitives) | * **Vector Components** (Knob, Slider, Button, CycleButton, Keys) are opinionated: they aim to cover 90% of needs with fixed look-and-feel choices; not everything is customizable. They are themable, scale without pixelation, and have a default view. * **Raster Components** (film strip and image-based controls) are unopinionated: you supply the assets, so any visual representation is possible. They do not use the built-in theme system and may pixelate when scaled. * **Control Primitives** and **View Primitives** are non-opinionated building blocks: you compose a custom view and are responsible for styling and optimization. View primitives include vector primitives (SVG fragments) and may include other building blocks; use them when you need full control over appearance. ## Next steps * Use [Vector Components](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction) (e.g. [Knob](https://cutoff.dev/audio-ui/docs/latest/components/vector/knob), [Slider](https://cutoff.dev/audio-ui/docs/latest/components/vector/slider)) for ready-to-use, themable controls and [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features). * Use [Raster Components](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction) when you have bitmap assets (sprite sheets or images) and want pixel-accurate or custom visuals. * Use [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) and [View Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-customization/view-system-view-primitives) to build fully custom controls. --- # FAQ # FAQ > Frequently asked questions about AudioUI, installation, usage, and support. ## General Questions ### What is AudioUI? AudioUI is a React component library for building user interfaces in audio and MIDI applications. For an overview of what it provides and its design philosophy, see the [Introduction](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction). ### Is AudioUI production-ready? AudioUI is in **Developer Preview**; pin to specific versions for production use. For current status, in-progress work, and 1.0 plans, see [Introduction – Project Status](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction#project-status). ### What React version is required? AudioUI requires React 18.2.0 or higher. This is specified as a peer dependency, so you'll need to ensure your project uses a compatible React version. AudioUI supports both React 18 and React 19 without any compatibility issues. ### What license does AudioUI use? AudioUI is dual-licensed: * **GPL-3.0-only**: Free for open-source projects * **Commercial License**: Required for proprietary, closed-source applications. Available at [cutoff.dev](https://cutoff.dev) ## Installation and Setup ### How do I install AudioUI? Install the package using your package manager: ### pnpm ```bash pnpm add @cutoff/audio-ui-react ``` ### npm ```bash npm install @cutoff/audio-ui-react ``` ### yarn ```bash yarn add @cutoff/audio-ui-react ``` ### bun ```bash bun add @cutoff/audio-ui-react ``` Don't forget to import the CSS: ```tsx import "@cutoff/audio-ui-react/style.css"; ``` See the [Installation Guide](https://cutoff.dev/audio-ui/docs/latest/getting-started/installation) for detailed instructions. ### Do I need to install peer dependencies? Yes. AudioUI requires React and React DOM as peer dependencies. If they're not already in your project, install them: ### pnpm ```bash pnpm add react@^19.0.0 react-dom@^19.0.0 ``` ### npm ```bash npm install react@^19.0.0 react-dom@^19.0.0 ``` ### yarn ```bash yarn add react@^19.0.0 react-dom@^19.0.0 ``` ### bun ```bash bun add react@^19.0.0 react-dom@^19.0.0 ``` ### Which frameworks are supported? AudioUI is a React library, so it works with any React-based framework. We provide detailed installation guides for: * Vite * Next.js * Tauri See the [Installation](https://cutoff.dev/audio-ui/docs/latest/getting-started/installation) section for framework-specific guides. ## Usage ### How do I customize the appearance? AudioUI provides a ThemeManager for theming. You can customize the primary color and roundness attribute: ```tsx import { setThemeColor, setThemeRoundness } from "@cutoff/audio-ui-react"; setThemeColor("#3b82f6"); setThemeRoundness(0.3); ``` The theme system currently supports primary color and roundness. For an overview of theming on vector components, see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features) in the Vector introduction. Additional theme options (glowness, reflectiveness, and more) are planned for the 1.0 release. Components also support multiple visual variants. For example, Knob has variants like `abstract`, `simplest`, `plainCap`, and `iconCap`, while Slider has variants like `abstract`, `trackless`, `trackfull`, and `stripless`. You can fine-tune components using styles and props. For advanced customization, you can use the non-opinionated primitives to build completely custom components. The [customization page](https://playground.cutoff.dev/examples/customization) contains multiple examples of totally customized components, and its source code is available for reference. ### How do I handle parameter changes? AudioUI components use a controlled component pattern. You manage state in your component and pass it via props: ```tsx const [value, setValue] = useState(0.5); setValue(e.value)} label="Cutoff" /> ``` The `onChange` event provides the new value in the `e.value` property. ### Can I use AudioUI with other frameworks? The core package (`@cutoff/audio-ui-core`) is framework-agnostic and contains all business logic. Currently, only the React implementation (`@cutoff/audio-ui-react`) is available, but the architecture supports potential implementations for other frameworks like Solid or Vue. ## Technical Questions ### Does AudioUI support mobile devices? Yes. AudioUI components are responsive and touch-optimized, making them suitable for mobile applications. ### How do I use AudioUI with TypeScript? AudioUI is written entirely in TypeScript and provides full type definitions. No additional setup is required when using TypeScript. ### Can I use AudioUI in a server-side rendered (SSR) application? Yes, but you'll need to ensure components are only rendered on the client side. In Next.js, use the `"use client"` directive or render components conditionally. AudioUI components are client components by default. ## Support and Community ### Where can I get help? Playground, Discord, and GitHub — see [Introduction – Resources](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction#resources). ### How do I report a bug? Open an issue on the [GitHub repository](https://github.com/cutoff/audio-ui/issues) with: * Description of the issue * Steps to reproduce * Expected vs actual behavior * Your environment (React version, browser, etc.) ### Can I contribute to AudioUI? Yes! AudioUI is open source. Contributions are welcome. Check the repository for contribution guidelines and open issues labeled "good first issue" to get started. ### When will AudioUI reach version 1.0? We're actively working toward a stable 1.0 release. For planned additions and timeline, see [Introduction – Project Status](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction#project-status). Join our Discord to stay updated on progress and share your feedback. ### How can I request features or vote on upcoming features? A dedicated wishlist channel is available in the [Cutoff Discord server](https://discord.gg/7RB6t2xqYW). You can create feature requests and vote for the most wanted features. Community feedback helps prioritize development efforts. --- # Introduction # Vector Components > Overview of AudioUI's built-in vector components—what they share (layout, parameters, interaction, theming) and how they differ (Knob, Slider, Button, CycleButton, Keys). Vector components are the built-in, opinionated controls: [Knob](https://cutoff.dev/audio-ui/docs/latest/components/vector/knob), [Slider](https://cutoff.dev/audio-ui/docs/latest/components/vector/slider), [Button](https://cutoff.dev/audio-ui/docs/latest/components/vector/button), [CycleButton](https://cutoff.dev/audio-ui/docs/latest/components/vector/cycle-button), and [Keys](https://cutoff.dev/audio-ui/docs/latest/components/vector/keys). They are not just "vector vs raster": their design comes from a careful analysis of existing audio plugins and apps from many providers, and gathers the visual characteristics and variants found most often in real-world interfaces. The end-goal is to cover about 90% of the needs of most apps and plugins; the remaining 10% (advanced customization) is left to [control primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) and [vector primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-customization/view-system-view-primitives)—totally flexible, but more demanding and requiring care about performance and optimization. Built-in components are designed to optimize performance as far as possible. For how they fit with raster and primitives, see the [Components overview](https://cutoff.dev/audio-ui/docs/latest/getting-started/components) under Getting Started. ## What all vector components share Every vector component provides: * **Layout system**: AdaptiveBox with sizing modes (fixed sizes or adaptive), label positioning, and alignment. Labels can sit above or below, with configurable overflow and height. * **Parameter model**: Support for ad-hoc props (`min`, `max`, `label`, etc.) or the full [Audio Parameter](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/audio-parameters) model (Continuous, Discrete, or Boolean) for scaling, units, formatting, and MIDI. * **Interaction system**: Drag, wheel, and keyboard input with configurable sensitivity and modes. High-frequency state during interaction is handled so the rest of the tree does not re-render on every move. * **Accessibility**: ARIA attributes, focus management, and keyboard navigation. * **Theming**: Built-in support for primary color and roundness via ThemeManager or per-component props (`color`, `roundness`). Dark and light mode work out of the box. * **Visual variants**: Multiple variants per component (e.g. Knob: abstract, simplest, plainCap, iconCap; Slider: abstract, trackless, trackfull, stripless) so you can match different plugin or app styles. Vector components are SVG-based and scale without pixelation. They are the right choice when you want ready-to-use, themable controls without supplying your own assets. Details are in [Theming Features](#theming-features) below. ## Theming Features * **color**: Primary (accent) color for the component. Any valid CSS color. Can be set per component via the `color` prop or globally via ThemeManager (`setThemeColor`). Used for value indicators, active states, and accents. Dark and light mode work out of the box. * **roundness**: Controls corner/edge roundness, normalized 0.0–1.0. Set per component with the `roundness` prop or globally via `setThemeRoundness`. Affects tracks, caps, and buttons. * **Future theme attributes**: The theme system will expand; attributes such as glowness and reflectiveness are planned (tentative for 1.0.0). See [Introduction – Project Status](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction#project-status) for roadmap. * **Variants**: Most components have or will get multiple **variants** that change their aspect (e.g. Knob: abstract, simplest, plainCap, iconCap; Slider: abstract, trackless, trackfull, stripless). Use the `variant` prop; see each component's page for options. * **Scale markers**: Knob- and slider-style components have or will get options for **scale markers** (graduations and indices) so you can show tick marks, labels, or minimal scales. Details are on the [Knob](https://cutoff.dev/audio-ui/docs/latest/components/vector/knob) and [Slider](https://cutoff.dev/audio-ui/docs/latest/components/vector/slider) pages. ## Completeness and roadmap The vector components library is meant to expand over time: more components (e.g. XY pad, Pitch/Mod wheels and levers, additional keyboard-style controls) and more variants and easy customization (e.g. glowness, reflectiveness) as the theme system evolves. See [Theming Features](#theming-features) above for current and planned theme options. See [Introduction – Project Status](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction#project-status) for current and planned work. ## Next steps * [Knob](https://cutoff.dev/audio-ui/docs/latest/components/vector/knob) — rotary continuous control * [Slider](https://cutoff.dev/audio-ui/docs/latest/components/vector/slider) — linear continuous control (horizontal or vertical) * [Button](https://cutoff.dev/audio-ui/docs/latest/components/vector/button) — toggle (latch) or momentary * [CycleButton](https://cutoff.dev/audio-ui/docs/latest/components/vector/cycle-button) — discrete option cycling * [Keys](https://cutoff.dev/audio-ui/docs/latest/components/vector/keys) — piano keyboard --- # Knob # Knob > A rotary control component for continuous value adjustment with multiple visual variants and full theming support. The Knob component provides a circular control for continuous value adjustment. It shares the same layout, parameter model, interaction, and accessibility as other vector components; see the [Vector introduction](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction). * Multiple visual variants: abstract, simplest, plainCap, iconCap * Full theming support: color, roundness, thickness customization ## Props | Name | Type | Default | Required | Description | | :--------------------- | :------------------------------------------------------------------- | :-------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | value | number | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | min | number | - | No | Minimum value (ad-hoc mode) | | max | number | - | No | Maximum value (ad-hoc mode) | | step | number | 1 | No | Step size for value adjustments | | bipolar | boolean | false | No | Whether the component should operate in bipolar mode (centered at zero) | | label | string | - | No | Label displayed below the component | | variant | "abstract" \| "simplest" \| "plainCap" \| "iconCap" | abstract | No | Visual variant of the knob | | thickness | number | - | No | Thickness of the knob's stroke (normalized 0.0-1.0, maps to 1-20) | | openness | number | 90 | No | Openness of the ring in degrees (0-360º; 0º closed, 90º 3/4 open, 180º half-circle) | | rotation | number | 0 | No | Optional rotation angle offset in degrees | | rotaryOverlay | boolean | false | No | Whether to use RotaryImage (true) or RadialImage (false) for iconCap overlay. Only applies when variant is "iconCap" and children is provided. | | children | React.ReactNode | - | No | SVG content to display as overlay in iconCap variant. Typically an icon component that will be rendered at the center of the knob. | | valueAsLabel | "labelOnly" \| "valueOnly" \| "interactive" | labelOnly | No | Controls how the label and value are displayed | | color | string | - | No | Component primary color - any valid CSS color value | | roundness | number | - | No | Roundness for component corners (normalized 0.0-1.0) | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | ContinuousParameter | - | No | Audio Parameter definition (Model). If provided, overrides min/max/step/label/bipolar from ad-hoc props | | valueFormatter | (value: number, parameterDef: AudioParameter) => string \| undefined | - | No | Custom renderer for the value display | | interactionMode | "drag" \| "wheel" \| "both" | both | No | Interaction mode | | interactionSensitivity | number | - | No | Sensitivity of the control (normalized value change per pixel/unit) | | interactionDirection | InteractionDirection | - | No | Direction of the interaction | ## Basic Usage The Knob component requires a `value` and `onChange` handler. In ad-hoc mode, you provide `min` and `max` to define the value range: ```tsx title="BasicKnob.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function BasicKnob() { const [value, setValue] = useState(50); return ( setValue(e.value)} min={0} max={100} size="large" label="Volume" /> ); } ``` ## Variants The Knob component supports four visual variants, each with a distinct appearance: ### Simplest A simplified version with minimal visual elements: ```tsx title="SimplestVariant.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function SimplestVariant() { const [value, setValue] = useState(0.5); return ( setValue(e.value)} variant="simplest" label="Resonance" size="large" /> ); } ``` ### Abstract The default variant with a clean, minimal design. Displays the current value as text in the center: ```tsx title="AbstractVariant.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function AbstractVariant() { const [value, setValue] = useState(0.5); return ( setValue(e.value)} variant="abstract" label="Cutoff" min={0.2} max={1} size="large" /> ); } ``` ### PlainCap A variant with a plain cap design: ```tsx title="PlainCapVariant.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function PlainCapVariant() { const [value, setValue] = useState(0.5); return ( setValue(e.value)} variant="plainCap" label="Gain" size="large" /> ); } ``` ### IconCap The iconCap variant allows you to display custom SVG content (typically icons) at the center of the knob. The icon can rotate with the knob value or remain static: ```tsx title="IconCapVariant.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function IconCapExample() { const [staticValue, setStaticValue] = useState(0); const [rotaryValue, setRotaryValue] = useState(0); return (
setStaticValue(e.value)} min={-64} max={64} bipolar={true} rotaryOverlay={false} size="large" label="Static icon" > setRotaryValue(e.value)} min={-64} max={64} bipolar={true} rotaryOverlay={true} size="large" label="Rotary Icon" >
); } ``` The `rotaryOverlay` prop controls whether the icon rotates with the knob value (`true`) or remains static (`false`). The icon inherits color via `currentColor`, so it adapts to light/dark mode automatically. The example above matches the LFO knob from the AudioUI playground (iconCap with SquareWaveIcon); the playground provides sine, triangle, square, and saw wave icons you can reuse. ## Theming Vector components share common theming features; see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features) in the Vector introduction for an overview. The Knob component supports theming through the `color` and `roundness` props, or via the global theme system: ### Color Customization You can customize the knob's primary color using the `color` prop: ```tsx title="CustomColor.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function CustomColor() { const [blueValue, setBlueValue] = useState(0.5); const [redValue, setRedValue] = useState(0.5); return (
setBlueValue(e.value)} color="#3b82f6" size="large" label="Blue Knob" /> setRedValue(e.value)} color="#ef4444" size="large" label="Red Knob" />
); } ``` ### Roundness Control the roundness of the knob's corners: ```tsx title="RoundnessExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function RoundnessExample() { const [square, setSquare] = useState(0.5); const [rounded, setRounded] = useState(0.5); const [circle, setCircle] = useState(0.5); return (
setSquare(e.value)} roundness={0.0} size="large" label="Square" /> setRounded(e.value)} roundness={0.5} size="large" label="Rounded" /> setCircle(e.value)} roundness={1.0} size="large" label="Fully Rounded" />
); } ``` > **Note:** **Value strip roundness**: For the knob's value strips (the arc that shows the current value), roundness behaves in an on/off way: `roundness={0.0}` uses a square linecap, and any other value uses a round linecap. The correct behaviour has been achieved internally but does not pass our performance requirements, so the current binary behaviour is used. ### Thickness Adjust the stroke thickness of the knob ring: ```tsx title="ThicknessExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function ThicknessExample() { const [thin, setThin] = useState(0.5); const [medium, setMedium] = useState(0.5); const [thick, setThick] = useState(0.5); return (
setThin(e.value)} thickness={0.2} size="large" label="Thin" /> setMedium(e.value)} thickness={0.5} size="large" label="Medium" /> setThick(e.value)} thickness={0.8} size="large" label="Thick" />
); } ``` ## Ring Configuration ### Openness The `openness` prop controls how much of the ring is visible. It accepts values in degrees (0-360º): * `0º`: Closed ring (full circle) * `90º`: 3/4 open (default) * `180º`: Half-circle * `270º`: 1/4 open ```tsx title="OpennessExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function OpennessExample() { const [closed, setClosed] = useState(0.5); const [defaultOpen, setDefaultOpen] = useState(0.5); const [half, setHalf] = useState(0.5); return (
setClosed(e.value)} openness={0} size="large" label="Closed" /> setDefaultOpen(e.value)} openness={90} size="large" label="Default (90º)" /> setHalf(e.value)} openness={180} size="large" label="Half Circle" />
); } ``` ### Rotation The `rotation` prop allows you to offset the starting angle of the ring: ```tsx title="RotationExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function RotationExample() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); return (
setV1(e.value)} rotation={0} size="large" label="No Rotation" /> setV2(e.value)} rotation={45} size="large" label="45º Rotation" /> setV3(e.value)} rotation={90} size="large" label="90º Rotation" />
); } ``` ## Value Display The `valueAsLabel` prop controls how the label and value are displayed: * `"labelOnly"`: Always shows the label (default) * `"valueOnly"`: Always shows the value * `"interactive"`: Shows label normally, but temporarily swaps to value during interaction ```tsx title="ValueDisplayExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function ValueDisplayExample() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); return (
setV1(e.value)} valueAsLabel="labelOnly" size="large" label="Label" /> setV2(e.value)} valueAsLabel="valueOnly" size="large" label="Volume" /> setV3(e.value)} valueAsLabel="interactive" size="large" label="Interactive" />
); } ``` ## Bipolar Mode In bipolar mode, the knob visualizes values relative to a center point rather than from minimum to maximum. This is useful for controls like pan or balance: ```tsx title="BipolarExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function BipolarExample() { const [value, setValue] = useState(0); return ( setValue(e.value)} min={-100} max={100} bipolar={true} size="large" label="Pan" /> ); } ``` ## Value Formatting You can customize how values are displayed using the `valueFormatter` prop. AudioUI provides built-in formatters for common audio parameters: ```tsx title="FormatterExample.tsx" import { useState } from "react"; import { Knob, frequencyFormatter, percentageFormatter, } from "@cutoff/audio-ui-react"; export default function FormatterExample() { const [frequency, setFrequency] = useState(1000); const [mix, setMix] = useState(50); return (
setFrequency(e.value)} min={20} max={20000} label="Frequency" size="large" valueFormatter={(value) => frequencyFormatter(value)} /> setMix(e.value)} min={0} max={100} label="Mix" size="large" valueFormatter={(value, paramDef) => { return percentageFormatter(value, paramDef.min, paramDef.max); }} />
); } ``` ## Parameter Model Instead of using ad-hoc props (`min`, `max`, `label`), you can provide a full parameter model via the `parameter` prop. This is useful when integrating with audio parameter systems: ```tsx title="ParameterModelExample.tsx" showLineNumbers import { Knob, createContinuousParameter } from "@cutoff/audio-ui-react"; const cutoffParam = createContinuousParameter({ paramId: "cutoff", label: "Cutoff", min: 20, max: 20000, unit: "Hz", scale: "log", defaultValue: 1000, }); export default function ParameterModelExample() { const [value, setValue] = useState(1000); return ( setValue(e.value)} /> ); } ``` ## Adaptive Sizing The Knob component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="SizingExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function SizingExample() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); const [v4, setV4] = useState(0.5); return (
setV1(e.value)} size="small" label="Small" /> setV2(e.value)} size="normal" label="Normal" /> setV3(e.value)} size="large" label="Large" /> setV4(e.value)} size="xlarge" label="XLarge" />
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="AdaptiveSize.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function AdaptiveSize() { const [wideValue, setWideValue] = useState(0.5); const [tallValue, setTallValue] = useState(0.5); const [distortedValue, setDistortedValue] = useState(0.5); return (
setWideValue(e.value)} adaptiveSize={true} label="Wide" />
setTallValue(e.value)} adaptiveSize={true} label="Tall" />
setDistortedValue(e.value)} adaptiveSize={true} displayMode="fill" label="Distorted" />
); } ``` ## Interaction Modes Control how users interact with the knob: ```tsx title="InteractionExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function InteractionExample() { const [dragVal, setDragVal] = useState(0.5); const [wheelVal, setWheelVal] = useState(0.5); const [bothVal, setBothVal] = useState(0.5); return (
setDragVal(e.value)} interactionMode="drag" label="Drag Only" size="large" /> setWheelVal(e.value)} interactionMode="wheel" label="Wheel Only" size="large" /> setBothVal(e.value)} interactionMode="both" label="Drag & Wheel" size="large" />
); } ``` You can also adjust the sensitivity of interactions: ```tsx title="SensitivityExample.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function SensitivityExample() { const [lowVal, setLowVal] = useState(0.5); const [highVal, setHighVal] = useState(0.5); return (
setLowVal(e.value)} interactionSensitivity={0.01} label="Low Sensitivity" size="large" /> setHighVal(e.value)} interactionSensitivity={0.1} label="High Sensitivity" size="large" />
); } ``` ## Common Use Cases ### Audio Filter Control ```tsx title="FilterControl.tsx" import { useState } from "react"; import { Knob, frequencyFormatter } from "@cutoff/audio-ui-react"; export default function FilterControl() { const [cutoff, setCutoff] = useState(1000); return ( frequencyFormatter(value)} unit="Hz" scale="log" onChange={(e) => setCutoff(e.value)} /> ); } ``` ### Volume Control ```tsx title="VolumeControl.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function VolumeControl() { const [volume, setVolume] = useState(50); return ( setVolume(e.value)} /> ); } ``` ### Pan Control ```tsx title="PanControl.tsx" import { useState } from "react"; import { Knob } from "@cutoff/audio-ui-react"; export default function PanControl() { const [pan, setPan] = useState(0); return ( setPan(e.value)} /> ); } ``` ## Next Steps * Explore the [Slider component](https://cutoff.dev/audio-ui/docs/latest/components/vector/slider) for linear controls * Learn about [Button](https://cutoff.dev/audio-ui/docs/latest/components/vector/button) and [CycleButton](https://cutoff.dev/audio-ui/docs/latest/components/vector/cycle-button) for discrete interactions * Check out [ImageKnob](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-knob) for custom bitmap-based knobs * Visit the [playground](https://playground.cutoff.dev) for interactive examples --- # Slider # Slider > A linear slider component for continuous value adjustment with support for both horizontal and vertical orientations. The Slider component provides a linear control for continuous value adjustment. It shares the same layout, parameter model, interaction, and accessibility as other vector components; see the [Vector introduction](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction). * Multiple visual variants: abstract, trackless, trackfull, stripless * Flexible orientation: horizontal and vertical layouts * Extensive cursor customization: image-based cursors, custom styling, aspect ratio control * Full theming support: color, roundness, thickness customization ## Props | Name | Type | Default | Required | Description | | :--------------------- | :------------------------------------------------------------------- | :-------- | :------- | :------------------------------------------------------------------------------------------------------ | | value | number | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | min | number | - | No | Minimum value (ad-hoc mode) | | max | number | - | No | Maximum value (ad-hoc mode) | | step | number | 1 | No | Step size for value adjustments | | bipolar | boolean | false | No | Whether the component should operate in bipolar mode (centered at zero) | | label | string | - | No | Label displayed below the component | | variant | "abstract" \| "trackless" \| "trackfull" \| "stripless" | abstract | No | Visual variant of the slider | | orientation | "horizontal" \| "vertical" | vertical | No | Orientation of the slider | | thickness | number | 0.5 | No | Thickness of the slider (normalized 0.0-1.0, maps to 1-50) | | valueAsLabel | "labelOnly" \| "valueOnly" \| "interactive" | labelOnly | No | Controls how the label and value are displayed | | cursorSize | "None" \| "Strip" \| "Track" \| "Tick" \| "Label" | - | No | Cursor size option - determines which component's width is used for the cursor | | cursorAspectRatio | number | - | No | Aspect ratio of the cursor | | cursorRoundness | number \| string | - | No | Overrides the roundness factor of the cursor. Defaults to \`roundness\` | | cursorImageHref | string | - | No | Optional image URL to display as cursor | | cursorClassName | string | - | No | Optional CSS class name for the cursor | | cursorStyle | React.CSSProperties | - | No | Optional inline styles for the cursor | | color | string | - | No | Component primary color - any valid CSS color value | | roundness | number | - | No | Roundness for component corners (normalized 0.0-1.0) | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | ContinuousParameter | - | No | Audio Parameter definition (Model). If provided, overrides min/max/step/label/bipolar from ad-hoc props | | valueFormatter | (value: number, parameterDef: AudioParameter) => string \| undefined | - | No | Custom renderer for the value display | | interactionMode | "drag" \| "wheel" \| "both" | both | No | Interaction mode | | interactionSensitivity | number | - | No | Sensitivity of the control (normalized value change per pixel/unit) | | interactionDirection | InteractionDirection | - | No | Direction of the interaction | ## Basic Usage The Slider component requires a `value` and `onChange` handler. By default, sliders are vertical: ```tsx title="BasicSlider.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function BasicSlider() { const [value, setValue] = useState(50); return (
setValue(e.value)} min={0} max={100} size="large" label="Volume" />
); } ``` ## Orientation Sliders can be oriented horizontally or vertically: ### Vertical Slider The default orientation, suitable for fader-style controls: ```tsx title="VerticalSlider.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function VerticalSlider() { const [value, setValue] = useState(0.7); return (
setValue(e.value)} orientation="vertical" label="Volume" min={0} max={1} size="large" />
); } ``` ### Horizontal Slider Useful for pan controls and other horizontal adjustments: ```tsx title="HorizontalSlider.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function HorizontalSlider() { const [value, setValue] = useState(0); return (
setValue(e.value)} orientation="horizontal" label="Pan" min={-100} max={100} bipolar={true} size="large" />
); } ``` ## Variants The Slider component supports four visual variants: ### Abstract The default variant with a clean, minimal design: ```tsx title="AbstractVariant.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function AbstractVariant() { const [value, setValue] = useState(0.5); return (
setValue(e.value)} variant="abstract" label="Volume" size="large" />
); } ``` ### Trackless A variant without a visible track: ```tsx title="TracklessVariant.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function TracklessVariant() { const [value, setValue] = useState(0.5); return (
setValue(e.value)} variant="trackless" label="Gain" size="large" />
); } ``` ### Trackfull A variant with a full track visible: ```tsx title="TrackfullVariant.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function TrackfullVariant() { const [value, setValue] = useState(0.5); return (
setValue(e.value)} variant="trackfull" label="Cutoff" size="large" />
); } ``` ### Stripless A variant without a value strip: ```tsx title="StriplessVariant.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function StriplessVariant() { const [value, setValue] = useState(0.5); return (
setValue(e.value)} variant="stripless" label="Resonance" size="large" />
); } ``` ## Cursor Customization The Slider component provides extensive options for customizing the cursor appearance: ### Cursor Size The `cursorSize` prop determines which component's width is used for the cursor: ```tsx title="CursorSizeExample.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function CursorSizeExample() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); return (
setV1(e.value)} cursorSize="Strip" size="large" label="Strip Cursor" /> setV2(e.value)} cursorSize="Track" size="large" label="Track Cursor" />
); } ``` ### Cursor Aspect Ratio Control the aspect ratio of the cursor: ```tsx title="CursorAspectRatio.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function CursorAspectRatio() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); return (
setV1(e.value)} cursorAspectRatio={1.0} size="large" label="Square Cursor" /> setV2(e.value)} cursorAspectRatio={2.0} size="large" label="Tall Cursor" />
); } ``` ### Cursor Roundness Override the roundness of the cursor independently from the slider: ```tsx title="CursorRoundness.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function CursorRoundness() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); return (
setV1(e.value)} cursorRoundness={0.0} size="large" label="Square Cursor" /> setV2(e.value)} cursorRoundness={1.0} size="large" label="Fully Rounded" />
); } ``` ### Custom Cursor Image Use a custom image for the cursor: ```tsx title="CursorImage.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function CursorImage() { const [value, setValue] = useState(0.5); return (
setValue(e.value)} cursorImageHref="/images/documentation/svg-primitives-radial-light.png" size="large" label="Custom Cursor" />
); } ``` ### Cursor Styling Apply custom CSS classes or inline styles to the cursor: ```tsx title="CursorStyling.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function CursorStyling() { const [value, setValue] = useState(0.5); return (
setValue(e.value)} cursorClassName="custom-cursor" cursorStyle={{ border: "2px solid #3b82f6" }} size="large" label="Styled Cursor" />
); } ``` ## Theming Vector components share common theming features; see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features) in the Vector introduction for an overview. The Slider component supports theming through the `color` and `roundness` props: ### Color Customization ```tsx title="SliderColor.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderColor() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); return (
setV1(e.value)} color="#3b82f6" size="large" label="Blue Slider" /> setV2(e.value)} color="#ef4444" size="large" label="Red Slider" />
); } ``` ### Roundness Control the roundness of the slider track and cursor: ```tsx title="SliderRoundness.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderRoundness() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); return (
setV1(e.value)} roundness={0.0} size="large" label="Square" /> setV2(e.value)} roundness={0.5} size="large" label="Rounded" /> setV3(e.value)} roundness={1.0} size="large" label="Fully Rounded" />
); } ``` ### Thickness Adjust the thickness of the slider track: ```tsx title="SliderThickness.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderThickness() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); return (
setV1(e.value)} thickness={0.2} size="large" label="Thin" /> setV2(e.value)} thickness={0.5} size="large" label="Medium" /> setV3(e.value)} thickness={0.8} size="large" label="Thick" />
); } ``` ## Bipolar Mode In bipolar mode, the slider visualizes values relative to a center point. This is ideal for pan controls: ```tsx title="BipolarSlider.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function BipolarSlider() { const [value, setValue] = useState(0); return (
setValue(e.value)} min={-100} max={100} bipolar={true} orientation="horizontal" size="large" label="Pan" />
); } ``` ## Value Display The `valueAsLabel` prop controls how the label and value are displayed: ```tsx title="SliderValueDisplay.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderValueDisplay() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); return (
setV1(e.value)} valueAsLabel="labelOnly" size="large" label="Volume" /> setV2(e.value)} valueAsLabel="valueOnly" size="large" label="Volume" /> setV3(e.value)} valueAsLabel="interactive" size="large" label="Volume" />
); } ``` ## Value Formatting Customize how values are displayed using the `valueFormatter` prop: ```tsx title="SliderFormatter.tsx" import { useState } from "react"; import { Slider, frequencyFormatter } from "@cutoff/audio-ui-react"; export default function SliderFormatterExample() { const [frequency, setFrequency] = useState(1000); const [gain, setGain] = useState(0); return (
setFrequency(e.value)} min={20} max={20000} label="Frequency" valueFormatter={(value) => frequencyFormatter(value)} size="large" /> setGain(e.value)} min={-60} max={12} label="Gain" valueFormatter={(value) => `${Math.round(value)} dB`} size="large" />
); } ``` ## Parameter Model Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use `createContinuousParameter` and the `parameter` prop: ```tsx title="SliderParameterModel.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderParameterModelExample() { const [value, setValue] = useState(50); return (
setValue(e.value)} size="large" />
); } ``` ## Adaptive Sizing The Slider component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="SliderSizing.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderSizing() { const [v1, setV1] = useState(0.5); const [v2, setV2] = useState(0.5); const [v3, setV3] = useState(0.5); const [v4, setV4] = useState(0.5); return (
setV1(e.value)} size="small" label="Small" /> setV2(e.value)} size="normal" label="Normal" /> setV3(e.value)} size="large" label="Large" /> setV4(e.value)} size="xlarge" label="XLarge" />
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="SliderAdaptiveSize.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderAdaptiveSize() { const [wideValue, setWideValue] = useState(0.5); const [tallValue, setTallValue] = useState(0.5); const [distortedValue, setDistortedValue] = useState(0.5); return (
setWideValue(e.value)} adaptiveSize={true} orientation="horizontal" label="Wide" />
setTallValue(e.value)} adaptiveSize={true} label="Tall" />
setDistortedValue(e.value)} adaptiveSize={true} displayMode="fill" label="Distorted" />
); } ``` ## Interaction Modes Control how users interact with the slider: ```tsx title="SliderInteraction.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderInteractionExample() { const [dragVal, setDragVal] = useState(0.5); const [wheelVal, setWheelVal] = useState(0.5); const [bothVal, setBothVal] = useState(0.5); return (
setDragVal(e.value)} interactionMode="drag" label="Drag Only" size="large" /> setWheelVal(e.value)} interactionMode="wheel" label="Wheel Only" size="large" /> setBothVal(e.value)} interactionMode="both" label="Drag & Wheel" size="large" />
); } ``` Adjust the sensitivity of interactions: ```tsx title="SliderSensitivity.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function SliderSensitivityExample() { const [lowVal, setLowVal] = useState(0.5); const [highVal, setHighVal] = useState(0.5); return (
setLowVal(e.value)} interactionSensitivity={0.01} label="Low Sensitivity" size="large" /> setHighVal(e.value)} interactionSensitivity={0.1} label="High Sensitivity" size="large" />
); } ``` ## Common Patterns ### Volume Fader A typical vertical volume fader: ```tsx title="VolumeFader.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function VolumeFader() { const [volume, setVolume] = useState(70); return (
setVolume(e.value)} orientation="vertical" variant="trackfull" min={0} max={100} label="Volume" size="large" valueFormatter={(value) => `${Math.round(value)}%`} />
); } ``` ### Pan Control A horizontal pan control with bipolar mode: ```tsx title="PanControl.tsx" import { useState } from "react"; import { Slider } from "@cutoff/audio-ui-react"; export default function PanControl() { const [pan, setPan] = useState(0); return ( setPan(e.value)} orientation="horizontal" min={-100} max={100} bipolar={true} label="Pan" size="large" valueFormatter={(value) => { if (value === 0) return "C"; return value > 0 ? `R${Math.abs(value)}` : `L${Math.abs(value)}`; }} /> ); } ``` ## Next Steps * Explore the [Knob component](https://cutoff.dev/audio-ui/docs/latest/components/vector/knob) for rotary controls * Learn about [Button](https://cutoff.dev/audio-ui/docs/latest/components/vector/button) and [CycleButton](https://cutoff.dev/audio-ui/docs/latest/components/vector/cycle-button) for discrete interactions * Check out [FilmStripContinuousControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-continuous) for bitmap-based sliders * Visit the [playground](https://playground.cutoff.dev) for interactive examples --- # Button # Button > A button component for audio applications supporting both toggle (latch) and momentary modes with proper event handling. The Button component provides a customizable button for audio applications. It shares the same layout, parameter model, interaction, and accessibility as other vector components; see the [Vector introduction](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction). * Two operation modes: Latch (toggle) and momentary * Full theming support: color, roundness customization * Drag interactions: Proper handling of global mouse events to ensure reliable release behavior, and allow easy implementations of, for example, step sequencers and pads ## Props | Name | Type | Default | Required | Description | | :--------------- | :----------------------------------------------------- | :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | value | boolean | - | Yes | Current value of the button (true = pressed/active, false = released/inactive) | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | latch | boolean | false | No | Whether the button should latch (toggle between states) or momentary (only active while pressed). Ad-hoc mode only, ignored if parameter provided. | | label | string | - | No | Label displayed below the component | | color | string | - | No | Component primary color - any valid CSS color value | | roundness | number | - | No | Roundness for component corners (normalized 0.0-1.0) | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | displayMode | "scaleToFit" \| "fill" | scaleToFit | No | Layout mode for the control | | labelMode | "none" \| "hidden" \| "visible" | visible | No | Visibility of the label row | | labelPosition | "above" \| "below" | below | No | Vertical position of the label relative to the control | | labelAlign | "start" \| "center" \| "end" | center | No | Horizontal alignment of the label text | | labelOverflow | "ellipsis" \| "abbreviate" \| "auto" | auto | No | How to handle label text overflow | | labelHeightUnits | number | - | No | Label height in the same units as SVG viewBox height | | parameter | BooleanParameter | - | No | Audio Parameter definition (Model). If provided, overrides label/latch from ad-hoc props | | paramId | string | - | No | Identifier for the parameter this control represents | | midiResolution | MidiResolution | 7 | No | MIDI resolution in bits (ad-hoc mode, ignored if parameter provided) | | onClick | React.MouseEventHandler | - | No | Click event handler | | onMouseDown | React.MouseEventHandler | - | No | Mouse down event handler | | onMouseUp | React.MouseEventHandler | - | No | Mouse up event handler | | onMouseEnter | React.MouseEventHandler | - | No | Mouse enter event handler | | onMouseLeave | React.MouseEventHandler | - | No | Mouse leave event handler | | className | string | - | No | Additional CSS classes | | style | React.CSSProperties | - | No | Additional inline styles | ## Basic Usage The Button component requires a `value` (boolean) and `onChange` handler. The button operates in two modes: latch (toggle) or momentary. ### Latch Mode (Toggle) In latch mode, the button toggles between pressed and released states: ```tsx title="LatchButton.tsx" import { useState } from "react"; import { Button } from "@cutoff/audio-ui-react"; export default function LatchButtonExample() { const [isOn, setIsOn] = useState(false); return ( ); } ``` ## Layout Considerations The Keys component maintains proper piano key layout and proportions regardless of the number of keys or starting position. The component: * Automatically calculates white and black key positions * Maintains correct spacing between keys * Handles partial octaves correctly * Supports any number of keys from 1 to 128 The component uses SVG for rendering, ensuring crisp display at any size and proper scaling. ## Common Use Cases ### MIDI Keyboard Visualization ```tsx title="MIDIKeyboard.tsx" import { useState } from "react"; import { Keys } from "@cutoff/audio-ui-react"; export default function MIDIKeyboardExample() { const [activeNotes, setActiveNotes] = useState([]); const handleNoteChange = (e) => { if (e.value.active) { setActiveNotes((prev) => [...prev, e.value.note]); } else { setActiveNotes((prev) => prev.filter((n) => n !== e.value.note)); } }; return ( ); } ``` ### Piano Roll Display ```tsx title="PianoRoll.tsx" import { Keys } from "@cutoff/audio-ui-react"; export default function PianoRollExample() { const playedNotes = [60, 64, 67]; return ( ); } ``` ### Compact Keyboard Control ```tsx title="CompactKeyboardControl.tsx" import { useState } from "react"; import { Keys } from "@cutoff/audio-ui-react"; export default function CompactKeyboardControlExample() { const [notesOn, setNotesOn] = useState([]); const handleNoteChange = (e) => { if (e.value.active) { setNotesOn((prev) => [...prev, e.value.note]); } else { setNotesOn((prev) => prev.filter((n) => n !== e.value.note)); } }; return ( ); } ``` ## Next Steps * Explore other [vector components](https://cutoff.dev/audio-ui/docs/latest/components/vector) like [Knob](https://cutoff.dev/audio-ui/docs/latest/components/vector/knob) and [Slider](https://cutoff.dev/audio-ui/docs/latest/components/vector/slider) * Learn about [raster components](https://cutoff.dev/audio-ui/docs/latest/components/raster) for bitmap-based controls * Visit the [playground](https://playground.cutoff.dev) for interactive examples --- # Introduction # Raster Components > Overview of bitmap-based controls: film strip (sprite sheet) components and image-based components, with guidelines for asset usage. Raster components use bitmap graphics instead of SVG to render controls. They fall into two categories: **film strip** controls (sprite sheets) and **image** controls (single or paired bitmaps). Use them when you need a fixed visual style, assets from VST tools, or bitmap-only designs. Because their appearance comes from bitmap assets, raster components are not themable like the built-in vector components. They do not respond to theme changes (e.g. primary color, roundness). They do benefit from the rest of AudioUI: the sizing system, interaction system, audio parameter model, layout, and accessibility all apply. > **Note:** AudioUI will provide props to supply separate assets for light and dark mode. (Feature coming soon.) ## Two Categories ### Film Strip Components Film strip controls display one frame at a time from a **sprite sheet**: a single image file where multiple frames are stacked vertically or horizontally. Each frame corresponds to a value state (continuous position, discrete option, or boolean on/off). * [FilmStripContinuousControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-continuous): one frame per value along a continuous range (e.g. VU meter, rotary strip). * [FilmStripDiscreteControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-discrete): one frame per discrete option (e.g. multi-position switch, waveform strip). * [FilmStripBooleanControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-boolean): two frames for off/on (e.g. power switch, momentary button). ### Image Components Image controls use one or two bitmap images that are rotated or swapped by value. They do not use sprite sheets. * [ImageKnob](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-knob): one image rotated by a continuous value. * [ImageRotarySwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-rotary-switch): one image rotated to discrete positions. * [ImageSwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-switch): two images (off/on) swapped by a boolean value. ## Film Strips (Sprite Sheets) A film strip is a bitmap where every frame has the same size and frames are arranged in a single row or column. This format is an **industry standard** for VST and audio plugin GUIs: many plugins and authoring tools export controls as sprite sheets so the host or UI can show the correct frame for the current parameter value. The format is widely supported by tools such as [WebKnobMan](https://www.g200kg.com/en/webknobman/), which lets you design knobs and switches and export them as PNG (or other bitmap) sprite sheets. You can also find ready-made assets in the [WebKnobMan gallery](https://www.g200kg.com/en/webknobman/gallery.php), where users share knob and strip designs; from there you can download project files and use the EasyRendering function to export images with the frame size and count you need. ## Guidelines for Film Strip Assets Frame dimensions, frame count, and orientation are **fixed by the asset**. They are determined when the image is created (e.g. in WebKnobMan or another tool). Do not change them in code to match a different number of options or a different layout; that will break the display. * **Frame dimensions**: `frameWidth` and `frameHeight` must match the width and height of one frame in the sprite sheet. If the asset has 120×80 pixel frames, use `frameWidth={120}` and `frameHeight={80}`. * **Frame count**: `frameCount` must equal the total number of frames in the image. For a boolean strip that is 2 frames, use `frameCount={2}`. For a discrete strip with 8 states, use `frameCount={8}`. The number of options (or value range) in your component must match this count where applicable (e.g. discrete control options map 1:1 to frames). * **Orientation**: Frames are either stacked vertically (top to bottom) or horizontally (left to right). Set `orientation` to match how your sprite sheet is laid out. Default is `"vertical"`. * **One asset, one configuration**: When you use a given film strip image, use the same `frameWidth`, `frameHeight`, `frameCount`, and `orientation` everywhere that image is used. Do not reuse the same image with different frame counts or dimensions for different examples or screens. The look of each raster control is defined entirely by its bitmap; for theme-driven styling (color, roundness, etc.), use the [vector components](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction) instead and see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features). ## Performance Raster components follow the same performance priorities as the rest of AudioUI; for the overall approach, see [Introduction](https://cutoff.dev/audio-ui/docs/latest/getting-started/introduction) (Performance First). Bitmap-based rendering also has specific advantages in dense UIs. * **Bitmap compositing**: The browser draws a region of a decoded image (or sprite sheet) instead of recalculating vector paths. Updating the displayed frame or rotation is a cheap operation (e.g. changing which region is visible or applying a transform), so value changes do not trigger full redraws. * **Image reuse**: Controls that use the same `imageHref` (or the same film strip) share one decoded bitmap. The browser decodes and caches the image once; multiple instances on the page reuse that resource. This helps when you have many knobs or switches from the same asset. * **Film strips**: A single sprite sheet holds all frames. One network request and one decode serve every frame; switching value only changes which part of the image is shown. That keeps memory and draw cost predictable even with many discrete or continuous raster controls. * **Re-renders**: As with other AudioUI components, raster controls re-render only when their props or value change. The interaction system uses refs for high-frequency state during drag or wheel so that the rest of the tree is not updated on every move. For UIs with many identical-looking controls (e.g. a mixer strip of film strip faders or image knobs), raster components can be a good fit: one asset, one decode, and cheap updates per control. ## Completeness and roadmap Raster components are basically complete: all variants of film strip and image-based controls are covered. ## Next Steps * Use [FilmStripContinuousControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-continuous), [FilmStripDiscreteControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-discrete), or [FilmStripBooleanControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-boolean) for sprite sheet-based controls. * Use [ImageKnob](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-knob), [ImageRotarySwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-rotary-switch), or [ImageSwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-switch) for single- or dual-image controls. * Check the [playground](https://playground.cutoff.dev) for interactive raster examples. --- # FilmStripContinuousControl # FilmStripContinuousControl > A continuous control that displays frames from a filmstrip sprite sheet, supporting the industry-standard bitmap-based control representation. FilmStripContinuousControl is a continuous control that displays frames from a filmstrip sprite sheet. It supports the widely-used industry standard for control representation: bitmap sprite sheets (filmstrips). While bitmap-based visualization is more constrained than SVG (no dynamic theming, fixed visual appearance), this component shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). The frame displayed is determined by the normalized value (0-1 maps to frame 0 to frameCount-1). > **Note:** **No Theming Support**: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content. ## Props | Name | Type | Default | Required | Description | | :--------------------- | :------------------------------------------------------------------- | :-------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- | | value | number | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | min | number | - | No | Minimum value (ad-hoc mode) | | max | number | - | No | Maximum value (ad-hoc mode) | | step | number | - | No | Step size for value adjustments | | bipolar | boolean | false | No | Whether the component should operate in bipolar mode (centered at zero) | | label | string | - | No | Label displayed below the component | | frameWidth | number | - | Yes | Width of a single frame in the filmstrip (pixels) | | frameHeight | number | - | Yes | Height of a single frame in the filmstrip (pixels) | | frameCount | number | - | Yes | Total number of frames in the filmstrip sprite sheet | | imageHref | string | - | Yes | URL to the sprite sheet/filmstrip image | | orientation | "vertical" \| "horizontal" | vertical | No | Orientation of the filmstrip (frames stacked vertically or horizontally) | | frameRotation | number | 0 | No | Optional frame rotation in degrees | | invertValue | boolean | false | No | If true, inverts the normalized value (0.0 -> 1.0 and 1.0 -> 0.0). Useful for filmstrips where frame 0 represents the maximum value | | valueAsLabel | "labelOnly" \| "valueOnly" \| "interactive" | labelOnly | No | Controls how the label and value are displayed | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | ContinuousParameter | - | No | Audio Parameter definition (Model). If provided, overrides min/max/step/label/bipolar from ad-hoc props | | valueFormatter | (value: number, parameterDef: AudioParameter) => string \| undefined | - | No | Custom renderer for the value display | | interactionMode | "drag" \| "wheel" \| "both" | both | No | Interaction mode | | interactionDirection | "vertical" \| "horizontal" \| "circular" \| "both" | - | No | Direction of interaction | | interactionSensitivity | number | - | No | Sensitivity multiplier for interactions (default varies by control type) | ## Basic Usage FilmStripContinuousControl requires a filmstrip sprite sheet image and frame dimensions: ```tsx title="BasicFilmStrip.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function BasicFilmStripExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ## Filmstrip Configuration Filmstrips are bitmap sprite sheets containing multiple frames stacked vertically (default) or horizontally. Each frame represents a different value state. ### Frame Dimensions Specify the dimensions of a single frame: ```tsx title="FrameDimensions.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function FrameDimensionsExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ### Orientation Control whether frames are stacked vertically or horizontally: ```tsx title="Orientation.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function OrientationExample() { const [verticalVal, setVerticalVal] = useState(50); const [horizontalVal, setHorizontalVal] = useState(50); return (
setVerticalVal(e.value)} /> setHorizontalVal(e.value)} />
); } ``` ### Frame Rotation Rotate the entire filmstrip container: ```tsx title="FrameRotation.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function FrameRotationExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ### Value Inversion Invert the value mapping for filmstrips where frame 0 represents the maximum value: ```tsx title="ValueInversion.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function ValueInversionExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ## Value Mapping The component maps continuous values (0-1 normalized) to frame indices (0 to frameCount-1): * Value 0.0 (min) → Frame 0 * Value 1.0 (max) → Frame (frameCount - 1) * Intermediate values are linearly interpolated ## Parameter Model Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use `createContinuousParameter` and the `parameter` prop: ```tsx title="FilmStripParameterModel.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function FilmStripParameterModelExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ## Adaptive Sizing The FilmStripContinuousControl component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="FilmStripSizing.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function FilmStripSizingExample() { const [v1, setV1] = useState(50); const [v2, setV2] = useState(50); const [v3, setV3] = useState(50); const [v4, setV4] = useState(50); return (
setV1(e.value)} /> setV2(e.value)} /> setV3(e.value)} /> setV4(e.value)} />
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="FilmStripContinuousAdaptiveSize.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function FilmStripContinuousAdaptiveSize() { const [wideVal, setWideVal] = useState(50); const [tallVal, setTallVal] = useState(50); const [distortedVal, setDistortedVal] = useState(50); return (
setWideVal(e.value)} adaptiveSize={true} label="Wide" frameWidth={120} frameHeight={80} frameCount={48} imageHref="/images/demo/vu3.png" />
setTallVal(e.value)} adaptiveSize={true} label="Tall" frameWidth={120} frameHeight={80} frameCount={48} imageHref="/images/demo/vu3.png" />
setDistortedVal(e.value)} adaptiveSize={true} displayMode="fill" label="Distorted" frameWidth={120} frameHeight={80} frameCount={48} imageHref="/images/demo/vu3.png" />
); } ``` ## Interaction Modes Control how users interact with the filmstrip: ```tsx title="FilmStripInteraction.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function FilmStripInteractionExample() { const [dragVal, setDragVal] = useState(50); const [wheelVal, setWheelVal] = useState(50); return (
setDragVal(e.value)} /> setWheelVal(e.value)} />
); } ``` ## Common Use Cases ### VU Meter ```tsx title="VUMeter.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function VUMeterExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ### Rotary Knob ```tsx title="RotaryKnob.tsx" import { useState } from "react"; import { FilmStripContinuousControl } from "@cutoff/audio-ui-react"; export default function RotaryKnobExample() { const [value, setValue] = useState(5); return ( setValue(e.value)} /> ); } ``` ## Filmstrip Image Format Filmstrip images should follow these conventions: * **Vertical orientation (default)**: Frames stacked top to bottom * **Horizontal orientation**: Frames stacked left to right * **Frame dimensions**: All frames must have identical dimensions * **Frame count**: Total number of frames in the sprite sheet * **Compatibility**: Works with filmstrips exported from WebKnobMan and other VST development tools ## Next Steps * Explore [FilmStripDiscreteControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-discrete) for discrete parameter control * Learn about [FilmStripBooleanControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-boolean) for boolean switches * Check out the [playground](https://playground.cutoff.dev) for interactive examples --- # FilmStripDiscreteControl # FilmStripDiscreteControl > A discrete control that displays frames from a filmstrip sprite sheet, supporting the industry-standard bitmap-based control representation. FilmStripDiscreteControl is a discrete control that displays frames from a filmstrip sprite sheet. It supports the widely-used industry standard for control representation: bitmap sprite sheets (filmstrips). While bitmap-based visualization is more constrained than SVG (no dynamic theming, fixed visual appearance), this component shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). The frame displayed is determined by mapping the current value to a frame index based on the number of options. > **Note:** **No Theming Support**: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content. ## Props | Name | Type | Default | Required | Description | | :------------ | :--------------------------------------------------------------------- | :------- | :------- | :----------------------------------------------------------------------------------------- | | value | string \| number | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | label | string | - | No | Label displayed below the component | | frameWidth | number | - | Yes | Width of a single frame in the filmstrip (pixels) | | frameHeight | number | - | Yes | Height of a single frame in the filmstrip (pixels) | | frameCount | number | - | Yes | Total number of frames in the filmstrip sprite sheet | | imageHref | string | - | Yes | URL to the sprite sheet/filmstrip image | | orientation | "vertical" \| "horizontal" | vertical | No | Orientation of the filmstrip (frames stacked vertically or horizontally) | | frameRotation | number | 0 | No | Optional frame rotation in degrees | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | DiscreteParameter | - | No | Audio Parameter definition (Model). If provided, overrides options/label from ad-hoc props | | options | Array<{ value: string \| number; label?: string; midiValue?: number }> | - | No | Array of option definitions (strict mode) | | children | React.ReactNode | - | No | OptionView children for ad-hoc or hybrid mode | ## Understanding Options vs Children FilmStripDiscreteControl distinguishes between two concepts: * **`options` prop**: Defines the parameter model (value, label, midiValue). Used for parameter structure. * **`children` (OptionView components)**: In this component, discrete visuals are handled by the filmstrip image (each frame), not by OptionView content. OptionView here is mainly syntactic sugar: it populates the option set in ad-hoc mode (values and count); the component uses the number of OptionView children to derive frame index. The visual content inside OptionView (e.g. text or icons) is never displayed. These serve different purposes and can be used together: use `options` or a `parameter` when you have data-driven option definitions or need MIDI mapping; use OptionView children for simple, ad-hoc setups when you want the option set inferred from the children. > **Note:** **Basic use**: For basic use of FilmStripDiscreteControl, and especially when using ad-hoc props (no `parameter` prop), prefer **OptionView** children. In that case the option set is inferred from the OptionViews and the frame count should match the number of options. Use the `options` prop or a full parameter when you need explicit parameter structure (e.g. data-driven options, MIDI mapping). For a full disambiguation of options vs OptionView, see [Options vs OptionView](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/options-and-optionview). ## Basic Usage FilmStripDiscreteControl requires a filmstrip sprite sheet image and frame dimensions. Use OptionView children to define the discrete options: ```tsx title="BasicFilmStripDiscrete.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function BasicFilmStripDiscreteExample() { const [value, setValue] = useState(4); return ( setValue(e.value)} > {[1, 2, 3, 4, 5, 6, 7, 8].map((n) => ( State {n} ))} ); } ``` ## Modes of Operation FilmStripDiscreteControl supports three modes of operation: ### Ad-Hoc Mode (Children Only) Model inferred from OptionView children: ```tsx title="AdHocFilmStripDiscrete.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function AdHocFilmStripDiscreteExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ### Strict Mode (Parameter Only) Model provided via parameter prop. The following example uses children (OptionView); with the full library you would use `createDiscreteParameter` and the `parameter` prop: ```tsx title="StrictModeFilmStripDiscrete.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function StrictModeFilmStripDiscreteExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ### Hybrid Mode (Parameter + Children) Model from parameter, View from children (matched by value). Use the same pattern as Strict Mode with OptionView children when the parameter is not in scope. ```tsx title="HybridModeFilmStripDiscrete.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function HybridModeFilmStripDiscreteExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ## Frame Mapping The component maps discrete option values to frame indices: * Option index 0 → Frame 0 * Option index 1 → Frame 1 * Option index N → Frame N The number of frames in the filmstrip should match the number of options. ## Filmstrip Configuration ### Frame Dimensions Specify the dimensions of a single frame: ```tsx title="FrameDimensions.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function FrameDimensionsExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ### Orientation Control whether frames are stacked vertically or horizontally: ```tsx title="Orientation.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function OrientationExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ### Frame Rotation Rotate the entire filmstrip container: ```tsx title="FrameRotation.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function FrameRotationExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ## Adaptive Sizing The FilmStripDiscreteControl component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="FilmStripDiscreteSizing.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function FilmStripDiscreteSizingExample() { const [v1, setV1] = useState(4); const [v2, setV2] = useState(4); const [v3, setV3] = useState(4); const [v4, setV4] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return (
setV1(e.value)} > {options.map((n) => ( State {n} ))} setV2(e.value)} > {options.map((n) => ( State {n} ))} setV3(e.value)} > {options.map((n) => ( State {n} ))} setV4(e.value)} > {options.map((n) => ( State {n} ))}
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="FilmStripDiscreteAdaptiveSize.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function FilmStripDiscreteAdaptiveSize() { const [wideVal, setWideVal] = useState(4); const [tallVal, setTallVal] = useState(4); const [distortedVal, setDistortedVal] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return (
setWideVal(e.value)} adaptiveSize={true} label="Wide" frameWidth={103} frameHeight={260} frameCount={8} imageHref="/images/demo/traffic-light-filmstrip.png" > {options.map((n) => ( State {n} ))}
setTallVal(e.value)} adaptiveSize={true} label="Tall" frameWidth={103} frameHeight={260} frameCount={8} imageHref="/images/demo/traffic-light-filmstrip.png" > {options.map((n) => ( State {n} ))}
setDistortedVal(e.value)} adaptiveSize={true} displayMode="fill" label="Distorted" frameWidth={103} frameHeight={260} frameCount={8} imageHref="/images/demo/traffic-light-filmstrip.png" > {options.map((n) => ( State {n} ))}
); } ``` ## Common Use Cases ### Traffic Light (Multiple States) ```tsx title="TrafficLight.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function TrafficLightExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ### Waveform Selector ```tsx title="WaveformSelector.tsx" import { useState } from "react"; import { FilmStripDiscreteControl, OptionView } from "@cutoff/audio-ui-react"; export default function WaveformSelectorExample() { const [value, setValue] = useState(4); const options = [1, 2, 3, 4, 5, 6, 7, 8]; return ( setValue(e.value)} > {options.map((n) => ( State {n} ))} ); } ``` ## Filmstrip Image Format Filmstrip images should follow these conventions: * **Vertical orientation (default)**: Frames stacked top to bottom * **Horizontal orientation**: Frames stacked left to right * **Frame dimensions**: All frames must have identical dimensions * **Frame count**: Must match the number of discrete options * **Compatibility**: Works with filmstrips exported from WebKnobMan and other VST development tools ## Next Steps * Explore [FilmStripContinuousControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-continuous) for continuous parameter control * Learn about [FilmStripBooleanControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-boolean) for boolean switches * Check out the [playground](https://playground.cutoff.dev) for interactive examples --- # FilmStripBooleanControl # FilmStripBooleanControl > A boolean control that displays frames from a filmstrip sprite sheet, supporting the industry-standard bitmap-based control representation. FilmStripBooleanControl is a boolean control that displays frames from a filmstrip sprite sheet. It supports the widely-used industry standard for control representation: bitmap sprite sheets (filmstrips). While bitmap-based visualization is more constrained than SVG (no dynamic theming, fixed visual appearance), this component shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). Typically uses 2 frames: frame 0 for false/off, frame 1 for true/on. > **Note:** **No Theming Support**: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content. ## Props | Name | Type | Default | Required | Description | | :------------ | :----------------------------------------------------- | :------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | | value | boolean | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | latch | boolean | false | No | Whether the button operates in latch (toggle) mode or momentary mode | | label | string | - | No | Label displayed below the component | | frameWidth | number | - | Yes | Width of a single frame in the filmstrip (pixels) | | frameHeight | number | - | Yes | Height of a single frame in the filmstrip (pixels) | | frameCount | number | - | Yes | Total number of frames in the filmstrip sprite sheet (typically 2 for boolean controls) | | imageHref | string | - | Yes | URL to the sprite sheet/filmstrip image | | orientation | "vertical" \| "horizontal" | vertical | No | Orientation of the filmstrip (frames stacked vertically or horizontally) | | frameRotation | number | 0 | No | Optional frame rotation in degrees | | invertValue | boolean | false | No | If true, inverts the normalized value (0.0 -> 1.0 and 1.0 -> 0.0). Useful for filmstrips where frame 0 represents "on" and frame 1 represents "off" | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | BooleanParameter | - | No | Audio Parameter definition (Model). If provided, overrides label/latch from ad-hoc props | ## Basic Usage FilmStripBooleanControl requires a filmstrip sprite sheet image with typically 2 frames (off and on states): ```tsx title="BasicFilmStripBoolean.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function BasicFilmStripBooleanExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ## Modes of Operation ### Latch Mode (Toggle) In latch mode, the button toggles between pressed and released states: ```tsx title="LatchFilmStripBoolean.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function LatchFilmStripBooleanExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Momentary Mode In momentary mode, the button is only active while being pressed: ```tsx title="MomentaryFilmStripBoolean.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function MomentaryFilmStripBooleanExample() { const [isPressed, setIsPressed] = useState(false); return ( setIsPressed(e.value)} /> ); } ``` ## Filmstrip Configuration ### Frame Dimensions Specify the dimensions of a single frame: ```tsx title="FrameDimensions.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function FrameDimensionsExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Orientation Control whether frames are stacked vertically or horizontally: ```tsx title="Orientation.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function OrientationExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Frame Rotation Rotate the entire filmstrip container: ```tsx title="FrameRotation.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function FrameRotationExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Value Inversion Invert the value mapping for filmstrips where frame 0 represents "on" and frame 1 represents "off": ```tsx title="ValueInversion.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function ValueInversionExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ## Frame Mapping The component maps boolean values to frames: * `false` (normalized 0.0) → Frame 0 * `true` (normalized 1.0) → Frame 1 When `invertValue` is true, the mapping is reversed: * `false` → Frame 1 * `true` → Frame 0 ## Parameter Model Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use `createBooleanParameter` and the `parameter` prop: ```tsx title="FilmStripBooleanParameterModel.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function FilmStripBooleanParameterModelExample() { const [value, setValue] = useState(false); return ( setValue(e.value)} /> ); } ``` ## Adaptive Sizing The FilmStripBooleanControl component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="FilmStripBooleanSizing.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function FilmStripBooleanSizingExample() { const [v1, setV1] = useState(false); const [v2, setV2] = useState(false); const [v3, setV3] = useState(false); const [v4, setV4] = useState(false); return (
setV1(e.value)} /> setV2(e.value)} /> setV3(e.value)} /> setV4(e.value)} />
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="FilmStripBooleanAdaptiveSize.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function FilmStripBooleanAdaptiveSize() { const [wideVal, setWideVal] = useState(false); const [tallVal, setTallVal] = useState(false); const [distortedVal, setDistortedVal] = useState(false); return (
setWideVal(e.value)} latch={true} adaptiveSize={true} label="Wide" frameWidth={64} frameHeight={64} frameCount={2} imageHref="/images/demo/switch_metal.png" />
setTallVal(e.value)} latch={true} adaptiveSize={true} label="Tall" frameWidth={64} frameHeight={64} frameCount={2} imageHref="/images/demo/switch_metal.png" />
setDistortedVal(e.value)} latch={true} adaptiveSize={true} displayMode="fill" label="Distorted" frameWidth={64} frameHeight={64} frameCount={2} imageHref="/images/demo/switch_metal.png" />
); } ``` ## Common Use Cases ### Power Switch ```tsx title="PowerSwitch.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function PowerSwitchExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Momentary Button ```tsx title="MomentaryButton.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function MomentaryButtonExample() { const [isPressed, setIsPressed] = useState(false); return ( setIsPressed(e.value)} /> ); } ``` ### Metal Switch ```tsx title="MetalSwitch.tsx" import { useState } from "react"; import { FilmStripBooleanControl } from "@cutoff/audio-ui-react"; export default function MetalSwitchExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ## Filmstrip Image Format Filmstrip images should follow these conventions: * **Frame count**: Typically 2 frames for boolean controls (off and on) * **Vertical orientation (default)**: Frames stacked top to bottom * **Horizontal orientation**: Frames stacked left to right * **Frame dimensions**: All frames must have identical dimensions * **Compatibility**: Works with filmstrips exported from WebKnobMan and other VST development tools ## Next Steps * Explore [FilmStripContinuousControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-continuous) for continuous parameter control * Learn about [FilmStripDiscreteControl](https://cutoff.dev/audio-ui/docs/latest/components/raster/filmstrip-discrete) for discrete parameter control * Check out the [playground](https://playground.cutoff.dev) for interactive examples --- # ImageKnob # ImageKnob > A continuous control that rotates an image based on a normalized value, perfect for custom knob designs using bitmap graphics. ImageKnob is a continuous control that rotates an image based on a normalized value. It shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). The image rotation is determined by the normalized value (0-1 maps to rotation based on openness and rotation offset). > **Note:** **No Theming Support**: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content. ## Props | Name | Type | Default | Required | Description | | :--------------------- | :------------------------------------------------------------------- | :-------- | :------- | :------------------------------------------------------------------------------------------------------ | | value | number | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | min | number | - | No | Minimum value (ad-hoc mode) | | max | number | - | No | Maximum value (ad-hoc mode) | | step | number | - | No | Step size for value adjustments | | bipolar | boolean | false | No | Whether the component should operate in bipolar mode (centered at zero) | | label | string | - | No | Label displayed below the component | | frameWidth | number | - | Yes | Width of the viewBox (determines viewBox width) | | frameHeight | number | - | Yes | Height of the viewBox (determines viewBox height) | | imageHref | string | - | Yes | URL to the image to rotate | | rotation | number | 0 | No | Optional rotation angle offset in degrees | | openness | number | 90 | No | Openness of the arc in degrees (value between 0-360º; 0º closed, 90º 3/4 open, 180º half-circle) | | valueAsLabel | "labelOnly" \| "valueOnly" \| "interactive" | labelOnly | No | Controls how the label and value are displayed | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | ContinuousParameter | - | No | Audio Parameter definition (Model). If provided, overrides min/max/step/label/bipolar from ad-hoc props | | valueFormatter | (value: number, parameterDef: AudioParameter) => string \| undefined | - | No | Custom renderer for the value display | | interactionMode | "drag" \| "wheel" \| "both" | both | No | Interaction mode | | interactionDirection | "vertical" \| "horizontal" \| "circular" \| "both" | - | No | Direction of interaction | | interactionSensitivity | number | - | No | Sensitivity multiplier for interactions (default varies by control type) | ## Basic Usage ImageKnob requires an image URL and frame dimensions: ```tsx title="BasicImageKnob.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function BasicImageKnobExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ## Rotation Configuration ### Openness Control the rotation range using the `openness` prop: ```tsx title="Openness.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function OpennessExample() { const [v90, setV90] = useState(50); const [v180, setV180] = useState(50); const [v270, setV270] = useState(50); return (
setV90(e.value)} /> setV180(e.value)} /> setV270(e.value)} />
); } ``` ### Rotation Offset Apply a rotation offset to align the image: ```tsx title="RotationOffset.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function RotationOffsetExample() { const [zeroVal, setZeroVal] = useState(50); const [rot45Val, setRot45Val] = useState(50); return (
setZeroVal(e.value)} /> setRot45Val(e.value)} />
); } ``` ## Parameter Model Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use `createContinuousParameter` and the `parameter` prop: ```tsx title="ImageKnobParameterModel.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function ImageKnobParameterModelExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ## Adaptive Sizing The ImageKnob component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="ImageKnobSizing.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function ImageKnobSizingExample() { const [v1, setV1] = useState(50); const [v2, setV2] = useState(50); const [v3, setV3] = useState(50); const [v4, setV4] = useState(50); return (
setV1(e.value)} /> setV2(e.value)} /> setV3(e.value)} /> setV4(e.value)} />
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="ImageKnobAdaptiveSize.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function ImageKnobAdaptiveSize() { const [wideVal, setWideVal] = useState(50); const [tallVal, setTallVal] = useState(50); const [distortedVal, setDistortedVal] = useState(50); return (
setWideVal(e.value)} adaptiveSize={true} label="Wide" frameWidth={100} frameHeight={100} imageHref="/images/demo/knob-volume.png" />
setTallVal(e.value)} adaptiveSize={true} label="Tall" frameWidth={100} frameHeight={100} imageHref="/images/demo/knob-volume.png" />
setDistortedVal(e.value)} adaptiveSize={true} displayMode="fill" label="Distorted" frameWidth={100} frameHeight={100} imageHref="/images/demo/knob-volume.png" />
); } ``` ## Interaction Modes Control how users interact with the knob: ```tsx title="ImageKnobInteraction.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function ImageKnobInteractionExample() { const [dragVal, setDragVal] = useState(50); const [wheelVal, setWheelVal] = useState(50); return (
setDragVal(e.value)} /> setWheelVal(e.value)} />
); } ``` ## Common Use Cases ### Volume Knob ```tsx title="VolumeKnob.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function VolumeKnobExample() { const [value, setValue] = useState(50); return ( setValue(e.value)} /> ); } ``` ### Tone Knob ```tsx title="ToneKnob.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function ToneKnobExample() { const [value, setValue] = useState(5); return ( setValue(e.value)} /> ); } ``` ### Direction Indicator ```tsx title="DirectionIndicator.tsx" import { useState } from "react"; import { ImageKnob } from "@cutoff/audio-ui-react"; export default function DirectionIndicatorExample() { const [value, setValue] = useState(3); return ( setValue(e.value)} /> ); } ``` ## Image Requirements * **Format**: Any image format supported by browsers (PNG, JPG, SVG, etc.) * **Dimensions**: The `frameWidth` and `frameHeight` props determine the viewBox dimensions * **Aspect Ratio**: The image will be scaled to fit the viewBox while preserving aspect ratio * **Rotation**: The image rotates around its center point based on the normalized value ## Rotation Calculation The rotation angle is calculated as: * Normalized value (0-1) maps to rotation range based on `openness` * `rotation` offset is added to align the image * For bipolar mode, the rotation is centered around the midpoint ## Next Steps * Explore [ImageRotarySwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-rotary-switch) for discrete rotary controls * Learn about [ImageSwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-switch) for boolean switches * Check out the [playground](https://playground.cutoff.dev) for interactive examples --- # ImageRotarySwitch # ImageRotarySwitch > A discrete control that rotates an image based on discrete option values, perfect for custom rotary switch designs using bitmap graphics. ImageRotarySwitch is a discrete control that rotates an image based on discrete option values. It shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). The image rotation is determined by mapping the current value to a normalized position, with snapping to discrete positions based on the number of options. > **Note:** **No Theming Support**: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content. ## Props | Name | Type | Default | Required | Description | | :----------- | :--------------------------------------------------------------------- | :------ | :------- | :----------------------------------------------------------------------------------------------- | | value | string \| number | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | label | string | - | No | Label displayed below the component | | frameWidth | number | - | Yes | Width of the viewBox (determines viewBox width) | | frameHeight | number | - | Yes | Height of the viewBox (determines viewBox height) | | imageHref | string | - | Yes | URL to the image to rotate | | rotation | number | 0 | No | Optional rotation angle offset in degrees | | openness | number | 90 | No | Openness of the arc in degrees (value between 0-360º; 0º closed, 90º 3/4 open, 180º half-circle) | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | DiscreteParameter | - | No | Audio Parameter definition (Model). If provided, overrides options/label from ad-hoc props | | options | Array<{ value: string \| number; label?: string; midiValue?: number }> | - | No | Array of option definitions (strict mode) | | children | React.ReactNode | - | No | OptionView children for ad-hoc or hybrid mode | ## Understanding Options vs Children ImageRotarySwitch distinguishes between two concepts: * **`options` prop**: Defines the parameter model (value, label, midiValue). Used for parameter structure. * **`children` (OptionView components)**: In this component, discrete visuals are handled by the raster image (rotation), not by OptionView content. OptionView here is mainly syntactic sugar: it populates the option set in ad-hoc mode (values and count); the component uses the number of OptionView children to derive rotation position. The visual content inside OptionView (e.g. text or icons) is never displayed. These serve different purposes and can be used together: use `options` or a `parameter` when you have data-driven option definitions or need MIDI mapping; use OptionView children for simple, ad-hoc setups when you want the option set inferred from the children. > **Note:** **Basic use**: For basic use of ImageRotarySwitch, and especially when using ad-hoc props (no `parameter` prop), prefer **OptionView** children. In that case the option set is inferred from the OptionViews. Use the `options` prop or a full parameter when you need explicit parameter structure (e.g. data-driven options, MIDI mapping). For a full disambiguation of options vs OptionView, see [Options vs OptionView](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/options-and-optionview). ## Basic Usage ImageRotarySwitch requires an image URL and frame dimensions. Use OptionView children to define the discrete options: ```tsx title="BasicImageRotarySwitch.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function BasicImageRotarySwitchExample() { const [value, setValue] = useState("low"); return ( setValue(e.value)} > Low Medium High ); } ``` ## Modes of Operation ImageRotarySwitch supports three modes of operation: ### Ad-Hoc Mode (Children Only) Model inferred from OptionView children: ```tsx title="AdHocImageRotarySwitch.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function AdHocImageRotarySwitchExample() { const [value, setValue] = useState("low"); return ( setValue(e.value)} > Low Medium High ); } ``` ### Strict Mode (Parameter Only) Model provided via parameter prop. The following example uses children (OptionView); with the full library you would use `createDiscreteParameter` and the `parameter` prop: ```tsx title="StrictModeImageRotarySwitch.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function StrictModeImageRotarySwitchExample() { const [value, setValue] = useState("low"); return ( setValue(e.value)} > Low Medium High ); } ``` ### Hybrid Mode (Parameter + Children) Model from parameter, View from children (matched by value). Use the same pattern as Strict Mode with OptionView children when the parameter is not in scope. ```tsx title="HybridModeImageRotarySwitch.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function HybridModeImageRotarySwitchExample() { const [value, setValue] = useState("low"); return ( setValue(e.value)} > Low Medium High ); } ``` ## Rotation Configuration ### Openness Control the rotation range using the `openness` prop: ```tsx title="Openness.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function OpennessExample() { const [value, setValue] = useState("medium"); return ( setValue(e.value)} > Low Medium High ); } ``` ### Rotation Offset Apply a rotation offset to align the image: ```tsx title="RotationOffset.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function RotationOffsetExample() { const [value, setValue] = useState("medium"); return ( setValue(e.value)} > Low Medium High ); } ``` ## Position Mapping The component maps discrete option values to rotation positions: * Option index 0 → Minimum rotation position * Option index N → Maximum rotation position * Intermediate positions are evenly distributed across the openness range ## Adaptive Sizing The ImageRotarySwitch component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="ImageRotarySwitchSizing.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function ImageRotarySwitchSizingExample() { const [v1, setV1] = useState("medium"); const [v2, setV2] = useState("medium"); const [v3, setV3] = useState("medium"); const [v4, setV4] = useState("medium"); return (
setV1(e.value)} > Low Medium High setV2(e.value)} > Low Medium High setV3(e.value)} > Low Medium High setV4(e.value)} > Low Medium High
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="ImageRotarySwitchAdaptiveSize.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function ImageRotarySwitchAdaptiveSize() { const [wideVal, setWideVal] = useState("medium"); const [tallVal, setTallVal] = useState("medium"); const [distortedVal, setDistortedVal] = useState("medium"); return (
setWideVal(e.value)} adaptiveSize={true} label="Wide" frameWidth={100} frameHeight={100} imageHref="/images/demo/knob-volume.png" > Low Medium High
setTallVal(e.value)} adaptiveSize={true} label="Tall" frameWidth={100} frameHeight={100} imageHref="/images/demo/knob-volume.png" > Low Medium High
setDistortedVal(e.value)} adaptiveSize={true} displayMode="fill" label="Distorted" frameWidth={100} frameHeight={100} imageHref="/images/demo/knob-volume.png" > Low Medium High
); } ``` ## Common Use Cases ### Volume Level Selector ```tsx title="VolumeLevelSelector.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function VolumeLevelSelectorExample() { const [value, setValue] = useState(2); return ( setValue(e.value)} > 0 1 2 3 4 ); } ``` ### Tone Selector ```tsx title="ToneSelector.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function ToneSelectorExample() { const [value, setValue] = useState("mid"); return ( setValue(e.value)} > Low Mid High ); } ``` ### Multi-Position Selector ```tsx title="MultiPositionSelector.tsx" import { useState } from "react"; import { ImageRotarySwitch, OptionView } from "@cutoff/audio-ui-react"; export default function MultiPositionSelectorExample() { const [value, setValue] = useState(5); return ( setValue(e.value)} > {Array.from({ length: 10 }, (_, i) => ( {i} ))} ); } ``` ## Image Requirements * **Format**: Any image format supported by browsers (PNG, JPG, SVG, etc.) * **Dimensions**: The `frameWidth` and `frameHeight` props determine the viewBox dimensions * **Aspect Ratio**: The image will be scaled to fit the viewBox while preserving aspect ratio * **Rotation**: The image rotates around its center point, snapping to discrete positions ## Rotation Calculation The rotation angle is calculated as: * Option index maps to normalized position (0 to 1) * Normalized position maps to rotation range based on `openness` * `rotation` offset is added to align the image * Positions snap to discrete option values ## Next Steps * Explore [ImageKnob](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-knob) for continuous rotary controls * Learn about [ImageSwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-switch) for boolean switches * Check out the [playground](https://playground.cutoff.dev) for interactive examples --- # ImageSwitch # ImageSwitch > A boolean control that displays one of two images based on state, perfect for on/off switches and buttons with custom bitmap graphics. ImageSwitch is a boolean control that displays one of two images based on the boolean value. It shares the same layout, parameter model, interaction, and accessibility as other controls (vector, raster, and control primitives); see the [Raster introduction](https://cutoff.dev/audio-ui/docs/latest/components/raster/introduction). The image displayed is determined by the boolean value: * `false` (normalized 0.0) displays `imageHrefFalse` * `true` (normalized 1.0) displays `imageHrefTrue` > **Note:** **No Theming Support**: This component does NOT support themable props (color, roundness, thickness) as visuals are entirely determined by the image content. ## Props | Name | Type | Default | Required | Description | | :------------- | :----------------------------------------------------- | :------ | :------- | :--------------------------------------------------------------------------------------- | | value | boolean | - | Yes | Current value of the control | | onChange | (event: AudioControlEvent\) => void | - | No | Handler for value changes | | latch | boolean | false | No | Whether the button operates in latch (toggle) mode or momentary mode | | label | string | - | No | Label displayed below the component | | frameWidth | number | - | Yes | Width of the viewBox (determines viewBox width) | | frameHeight | number | - | Yes | Height of the viewBox (determines viewBox height) | | imageHrefFalse | string | - | Yes | URL to the image for false/off state | | imageHrefTrue | string | - | Yes | URL to the image for true/on state | | adaptiveSize | boolean | false | No | Whether the component stretches to fill its container | | size | "xsmall" \| "small" \| "normal" \| "large" \| "xlarge" | normal | No | Size of the component | | parameter | BooleanParameter | - | No | Audio Parameter definition (Model). If provided, overrides label/latch from ad-hoc props | ## Basic Usage ImageSwitch requires two image URLs (one for off state, one for on state) and frame dimensions: ```tsx title="BasicImageSwitch.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function BasicImageSwitchExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ## Modes of Operation ### Latch Mode (Toggle) In latch mode, the button toggles between pressed and released states: ```tsx title="LatchImageSwitch.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function LatchImageSwitchExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Momentary Mode In momentary mode, the button is only active while being pressed: ```tsx title="MomentaryImageSwitch.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function MomentaryImageSwitchExample() { const [isPressed, setIsPressed] = useState(false); return ( setIsPressed(e.value)} /> ); } ``` ## Image Selection The component displays different images based on the boolean value: ```tsx title="ImageSelection.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function ImageSelectionExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ## Parameter Model Use a parameter model for integration with audio parameter systems. The following example uses ad-hoc props; with the full library you would use `createBooleanParameter` and the `parameter` prop: ```tsx title="ImageSwitchParameterModel.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function ImageSwitchParameterModelExample() { const [value, setValue] = useState(false); return ( setValue(e.value)} /> ); } ``` ## Adaptive Sizing The ImageSwitch component supports both fixed sizes and adaptive sizing. By default, the size of the component is driven by the [Size System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/size-system) and their `size` attribute: ```tsx title="ImageSwitchSizing.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function ImageSwitchSizingExample() { const [v1, setV1] = useState(false); const [v2, setV2] = useState(false); const [v3, setV3] = useState(false); const [v4, setV4] = useState(false); return (
setV1(e.value)} /> setV2(e.value)} /> setV3(e.value)} /> setV4(e.value)} />
); } ``` Adaptive sizing allows the component to adapt to the size of its parent container, adjusting its dimensions intelligently without causing distortion (`scaleToFit` display mode). The `fill` display mode makes the component fill the entire container, potentially distorting it. ```tsx title="ImageSwitchAdaptiveSize.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function ImageSwitchAdaptiveSize() { const [wideVal, setWideVal] = useState(false); const [tallVal, setTallVal] = useState(false); const [distortedVal, setDistortedVal] = useState(false); return (
setWideVal(e.value)} latch={true} adaptiveSize={true} label="Wide" frameWidth={100} frameHeight={100} imageHrefFalse="/images/demo/star-off.png" imageHrefTrue="/images/demo/star-on.png" />
setTallVal(e.value)} latch={true} adaptiveSize={true} label="Tall" frameWidth={100} frameHeight={100} imageHrefFalse="/images/demo/star-off.png" imageHrefTrue="/images/demo/star-on.png" />
setDistortedVal(e.value)} latch={true} adaptiveSize={true} displayMode="fill" label="Distorted" frameWidth={100} frameHeight={100} imageHrefFalse="/images/demo/star-off.png" imageHrefTrue="/images/demo/star-on.png" />
); } ``` ## Common Use Cases ### Favorite/Star Button ```tsx title="FavoriteButton.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function FavoriteButtonExample() { const [isFavorite, setIsFavorite] = useState(false); return ( setIsFavorite(e.value)} /> ); } ``` ### Power Switch ```tsx title="PowerSwitch.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function PowerSwitchExample() { const [isOn, setIsOn] = useState(false); return ( setIsOn(e.value)} /> ); } ``` ### Momentary Record Button ```tsx title="RecordButton.tsx" import { useState } from "react"; import { ImageSwitch } from "@cutoff/audio-ui-react"; export default function RecordButtonExample() { const [isRecording, setIsRecording] = useState(false); return ( setIsRecording(e.value)} /> ); } ``` ## Image Requirements * **Format**: Any image format supported by browsers (PNG, JPG, SVG, etc.) * **Dimensions**: The `frameWidth` and `frameHeight` props determine the viewBox dimensions * **Aspect Ratio**: Images will be scaled to fit the viewBox while preserving aspect ratio * **States**: Provide two separate images for off and on states ## Image Selection Logic The component selects images based on the boolean value: * `value === false` → Displays `imageHrefFalse` * `value === true` → Displays `imageHrefTrue` The selection is immediate and does not animate between states. ## Next Steps * Explore [ImageKnob](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-knob) for continuous rotary controls * Learn about [ImageRotarySwitch](https://cutoff.dev/audio-ui/docs/latest/components/raster/image-rotary-switch) for discrete rotary controls * Check out the [playground](https://playground.cutoff.dev) for interactive examples --- # Default Components Styling # Default Components Styling > Learn how to style AudioUI's default components using the built-in theming system, CSS variables, and theme management utilities. AudioUI's default components (Knob, Slider, Button, CycleButton, Keys) use a CSS variable-based theming system optimized for realtime audio applications. This system provides a clean, idiomatic way to customize component colors and styles without React Context or JavaScript overhead. For a high-level overview of theming on vector components, see [Theming Features](https://cutoff.dev/audio-ui/docs/latest/components/vector/introduction#theming-features) in the Vector introduction. **Note**: This styling system applies to AudioUI's built-in default components. Fully customized components built with [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) and custom view components use their own independent styling and theming systems. ## Why a CSS Variable System? Audio applications have strict performance requirements. The CSS variable approach ensures: * **Zero React overhead**: Theme changes don't trigger re-renders * **Automatic updates**: CSS handles theme changes instantly * **Dark mode support**: Automatic adaptation via CSS `.dark` class * **Animation support**: Colors can be animated smoothly * **Framework agnostic**: Works with any CSS-capable framework ## How It Works The color system uses a three-tier resolution hierarchy: 1. **Component prop** (`color` prop on individual components) 2. **Global CSS variable** (`--audioui-primary-color`) 3. **Adaptive default** (`--audioui-adaptive-default-color` - white in dark mode, black in light mode) When you set a color, AudioUI automatically computes variants (`primary50`, `primary20`) using CSS `color-mix()`. These variants are used for layered effects, borders, and visual depth. ## Basic Usage ### Setting Global Theme Use the theme utility functions to set a global theme that applies to all components: ```tsx title="GlobalTheme.tsx" showLineNumbers import { useEffect } from "react"; import { setThemeColor, setThemeRoundness } from "@cutoff/audio-ui-react"; import { Knob, Button } from "@cutoff/audio-ui-react"; export default function GlobalThemeExample() { useEffect(() => { // Set global theme (affects all components) setThemeColor("#3b82f6"); // Blue setThemeRoundness(0.3); // Slightly rounded }, []); return (
{}} label="Cutoff" />
); } ``` ### Using Predefined Colors AudioUI provides predefined theme colors for convenience: ```tsx title="PredefinedColors.tsx" showLineNumbers import { useEffect } from "react"; import { setThemeColor, themeColors } from "@cutoff/audio-ui-react"; import { Knob } from "@cutoff/audio-ui-react"; export default function PredefinedColorsExample() { useEffect(() => { // Use predefined colors setThemeColor(themeColors.blue); // Or: setThemeColor(themeColors.purple); // Or: setThemeColor(themeColors.orange); }, []); return {}} label="Volume" />; } ``` Available predefined colors: `default`, `blue`, `orange`, `pink`, `green`, `purple`, `yellow`. ### Per-Component Colors Override the global theme for individual components: ```tsx title="PerComponentColors.tsx" showLineNumbers import { Knob, Slider } from "@cutoff/audio-ui-react"; export default function PerComponentColorsExample() { return (
{}} label="Cutoff" color="#3b82f6" // Blue /> {}} label="Resonance" color="#ef4444" // Red /> {}} label="Volume" color="hsl(160, 95%, 44%)" // Green />
); } ``` ## Color Formats The `color` prop accepts any valid CSS color value: ```tsx title="ColorFormats.tsx" showLineNumbers import { Knob } from "@cutoff/audio-ui-react"; export default function ColorFormatsExample() { return (
{}} label="Named" color="blue" /> {}} label="Hex" color="#FF5500" /> {}} label="RGB" color="rgb(255, 85, 0)" /> {}} label="HSL" color="hsl(20, 100%, 50%)" /> {}} label="CSS Variable" color="var(--my-custom-color)" />
); } ``` ## Color Variants AudioUI automatically generates color variants from your primary color: * **`primary50`**: 50% opacity variant (for backgrounds, tracks) * **`primary20`**: 20% opacity variant (for subtle effects) These variants are computed using CSS `color-mix()`, so they update automatically when the primary color changes. Components use these variants for layered visual effects: ```tsx title="ColorVariants.tsx" showLineNumbers import { Knob, Slider } from "@cutoff/audio-ui-react"; export default function ColorVariantsExample() { return (
{/* Knob uses primary50 for background arc, primary for foreground */} {}} label="Knob" color="#3b82f6" /> {/* Slider uses primary50 for track, primary for fill */} {}} label="Slider" color="#3b82f6" orientation="vertical" />
); } ``` ## Adaptive Default Colors When no color is specified, components use an adaptive default that automatically switches between light and dark modes: * **Light mode**: Near-black (`hsl(0, 0%, 10%)`) * **Dark mode**: Near-white (`hsl(0, 0%, 96%)`) This ensures components are always visible regardless of your application's theme: ```tsx title="AdaptiveDefault.tsx" showLineNumbers import { Knob } from "@cutoff/audio-ui-react"; export default function AdaptiveDefaultExample() { // No color prop - uses adaptive default return {}} label="Adaptive" />; } ``` ## CSS-Only Customization You can customize themes using pure CSS without JavaScript: ```tsx title="CSSOnlyTheme.tsx" showLineNumbers export default function CSSOnlyThemeExample() { return ( <>
{}} label="Custom Theme" />
); } ``` Or using inline styles: ```tsx title="InlineCSSTheme.tsx" showLineNumbers import { Knob } from "@cutoff/audio-ui-react"; export default function InlineCSSThemeExample() { return (
{}} label="Inline Theme" />
); } ``` ## Roundness Control the roundness of component corners using the `roundness` prop or global theme: ```tsx title="Roundness.tsx" showLineNumbers import { Knob, Button } from "@cutoff/audio-ui-react"; export default function RoundnessExample() { return (
{}} label="Square" roundness={0.0} /> {}} label="Rounded" roundness={0.5} /> {}} label="Fully Rounded" roundness={1.0} />
); } ``` Set global roundness: ```tsx title="GlobalRoundness.tsx" showLineNumbers import { useEffect } from "react"; import { setThemeRoundness } from "@cutoff/audio-ui-react"; export default function GlobalRoundnessExample() { useEffect(() => { setThemeRoundness(0.3); // Applies to all components }, []); return {}} label="Themed" />; } ``` ## Dynamic Theme Switching Themes can be changed dynamically at runtime: ```tsx title="DynamicTheme.tsx" showLineNumbers import { useState } from "react"; import { setThemeColor, themeColors } from "@cutoff/audio-ui-react"; import { Knob } from "@cutoff/audio-ui-react"; export default function DynamicThemeExample() { const [currentTheme, setCurrentTheme] = useState(themeColors.blue); const themes = [ { name: "Blue", color: themeColors.blue }, { name: "Purple", color: themeColors.purple }, { name: "Orange", color: themeColors.orange }, { name: "Green", color: themeColors.green }, ]; const handleThemeChange = (color: string) => { setThemeColor(color); setCurrentTheme(color); }; return (
{themes.map((theme) => ( ))}
{}} label="Themed Knob" />
); } ``` ## Color Resolution in Practice Understanding the resolution hierarchy helps when debugging theme issues: 1. **Component prop takes precedence**: If you pass `color="red"` to a Knob, it uses red regardless of global theme 2. **Global theme is fallback**: If no `color` prop, components use `--audioui-primary-color` 3. **Adaptive default is final fallback**: If no global theme is set, components use the adaptive default ```tsx title="ResolutionExample.tsx" showLineNumbers import { useEffect } from "react"; import { setThemeColor, themeColors } from "@cutoff/audio-ui-react"; import { Knob } from "@cutoff/audio-ui-react"; export default function ResolutionExample() { useEffect(() => { setThemeColor(themeColors.blue); // Global theme }, []); return (
{/* Uses global blue theme */} {}} label="Global Theme" /> {/* Overrides with red */} {}} label="Override" color="red" />
); } ``` ## Scope: Default Components Only This styling system applies exclusively to AudioUI's default components: * **Knob** - All variants (abstract, simplest, plainCap, iconCap) * **Slider** - All variants (abstract, trackless, trackfull, stripless) * **Button** - All variants * **CycleButton** - All variants * **Keys** - All key styles **Custom components** built with [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) and custom view components do not use this styling system. They implement their own styling and theming independently. ## Best Practices 1. **Set global theme once**: Use `setThemeColor()` in your app's root component or layout 2. **Use predefined colors**: `themeColors` provides consistent, tested color values 3. **Override sparingly**: Use per-component colors only when needed for specific UI elements 4. **CSS variables for scoped themes**: Use CSS variables when you need theme scoping (e.g., different themes for different sections) 5. **Test in both modes**: Always verify your colors work in both light and dark modes ## Next Steps * Learn about [Default Components Sizing](https://cutoff.dev/audio-ui/docs/latest/customization/default-components-sizing) for component sizing * Explore [AdaptiveBox](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/adaptive-box-layout) for layout and responsive behavior * Explore [Audio Parameters](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/audio-parameters) for parameter-based theming * Check out [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) for building custom components with independent styling * See component-specific documentation for advanced styling options --- # Default Components Sizing # Default Components Sizing > Learn how to size AudioUI's default components using the built-in size system, from base units to multipliers, aspect ratios, and fixed vs adaptive sizing. AudioUI's default components (Knob, Slider, Button, CycleButton, Keys) use a base unit system for consistent sizing. This system ensures mathematical harmony between components and provides both fixed and adaptive sizing options. **Note**: This sizing system applies to AudioUI's built-in default components. Fully customized components built with [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) and custom view components use their own independent sizing systems. ## Overview The size system provides: * **Consistent sizing**: All components derive from a single base unit * **Mathematical harmony**: Components align perfectly in layouts * **Flexible sizing**: Choose between fixed sizes or adaptive container-filling * **Themeable**: Scale the entire system by changing the base unit ## Base Unit System All component sizes derive from a single base unit: * **Base Unit**: `--audioui-unit` (default: 48px) * **Size Multipliers**: * `xsmall`: 1x base unit (48px) * `small`: 1.25x base unit (60px) * `normal`: 1.5x base unit (72px) - default * `large`: 2x base unit (96px) * `xlarge`: 2.5x base unit (120px) ### CSS Variable Structure Size dimensions are defined using CSS variables: ```css /* Base unit */ --audioui-unit: 48px; /* Size multipliers */ --audioui-size-mult-xsmall: 1; --audioui-size-mult-small: 1.25; --audioui-size-mult-normal: 1.5; --audioui-size-mult-large: 2; --audioui-size-mult-xlarge: 2.5; /* Square components (Button, Knob, CycleButton) */ --audioui-size-square-{size}: calc(var(--audioui-unit) * var(--audioui-size-mult-{size})); /* Horizontal Slider (1x2) */ --audioui-size-hslider-height-{size}: calc(var(--audioui-unit) * multiplier); --audioui-size-hslider-width-{size}: calc(height * 2); /* Vertical Slider (2x1) */ --audioui-size-vslider-width-{size}: calc(var(--audioui-unit) * multiplier); --audioui-size-vslider-height-{size}: calc(width * 2); /* Keys (1x5) */ --audioui-size-keys-height-{size}: calc(var(--audioui-unit) * multiplier); --audioui-size-keys-width-{size}: calc(height * 5); ``` ## Component Aspect Ratios Each component type has a fixed aspect ratio that defines its shape: * **Button, Knob, CycleButton**: 1x1 (square) * **Horizontal Slider**: 1x2 (width:height) - width > height * **Vertical Slider**: 2x1 (width:height) - height > width * **Keys**: 1x5 (width:height) - width > height These aspect ratios are preserved at all sizes, ensuring components maintain their visual identity. ## Fixed Sizing When `adaptiveSize={false}` (default), components use fixed sizes based on the `size` prop: ```tsx title="FixedSizing.tsx" showLineNumbers import { Knob, Slider } from "@cutoff/audio-ui-react"; export default function FixedSizingExample() { return (
{}} label="Small" size="small" /> {}} label="Normal" size="normal" /> {}} label="Large" size="large" /> {}} label="Slider" size="normal" orientation="horizontal" />
); } ``` ### How Fixed Sizing Works 1. **CSS Classes**: Size class is applied for semantic purposes and external styling 2. **Inline Styles**: Size dimensions are applied as inline styles (CSS variable references) to override AdaptiveBox's default 100% sizing 3. **Precedence**: User `className` and `style` props take precedence over size classes/styles ## Adaptive Sizing When `adaptiveSize={true}`, components fill their container and ignore the `size` prop for layout constraints: ```tsx title="AdaptiveSizing.tsx" showLineNumbers import { Knob } from "@cutoff/audio-ui-react"; export default function AdaptiveSizingExample() { return (
{}} label="Adaptive" adaptiveSize={true} /> {}} label="Adaptive" adaptiveSize={true} />
); } ``` ### How Adaptive Sizing Works 1. No size class or inline size styles are applied 2. AdaptiveBox's default `width: 100%; height: 100%` takes effect 3. Component fills its container while maintaining aspect ratio ## Size Props All controls support a `size` prop and an `adaptiveSize` prop: ```typescript type SizeType = "xsmall" | "small" | "normal" | "large" | "xlarge"; type AdaptiveSizeProps = { size?: SizeType; // default: "normal" adaptiveSize?: boolean; // default: false }; ``` ## Customization ### Changing Base Unit Scale the entire size system by modifying the base unit: ```css :root { --audioui-unit: 60px; /* Increase from 48px to 60px */ } ``` All components will scale proportionally while maintaining their aspect ratios: * `xsmall`: 60px (was 48px) * `small`: 75px (was 60px) * `normal`: 90px (was 72px) * `large`: 120px (was 96px) * `xlarge`: 150px (was 120px) ### Overriding Size Users can override size constraints using `className` or `style` props. User-provided styles are spread after size styles, so they take precedence: ```tsx title="SizeOverride.tsx" showLineNumbers import { Knob } from "@cutoff/audio-ui-react"; export default function SizeOverrideExample() { return (
{/* CSS class override (if higher specificity) */} {}} label="CSS Override" size="normal" className="w-20 h-20" /> {/* Inline style override (always wins) */} {}} label="Inline Override" size="normal" style={{ width: "100px", height: "100px" }} />
); } ``` ## Design System Consistency The size system ensures mathematical harmony between components: * A "small" knob (1x1) aligns perfectly with a "small" slider's track width * All components use the same base unit and multipliers * Size variations are consistent across component types * Aspect ratios are preserved at all sizes ## Performance Considerations * **CSS Variables**: Size classes use CSS variables (computed at render time, cached by browser) * **No JavaScript Calculations**: All sizing is CSS-based * **Optimized Merging**: Simple object spread for style merging (no `useMemo` overhead needed) * **Memoization**: All controls are wrapped with `React.memo` - style objects are only created when props change ## Scope: Default Components Only This sizing system applies exclusively to AudioUI's default components: * **Knob** - All variants (abstract, simplest, plainCap, iconCap) * **Slider** - All variants (abstract, trackless, trackfull, stripless) * **Button** - All variants * **CycleButton** - All variants * **Keys** - All key styles **Custom components** built with [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) and custom view components do not use this sizing system. They implement their own sizing independently. ## Integration with AdaptiveBox The size system works in conjunction with [AdaptiveBox](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/adaptive-box-layout): * **Fixed Sizing**: Size dimensions override AdaptiveBox's default 100% sizing * **Adaptive Sizing**: AdaptiveBox's container-filling behavior takes effect * **Aspect Ratios**: Both systems respect component aspect ratios ## Next Steps * Learn about [Default Components Styling](https://cutoff.dev/audio-ui/docs/latest/customization/default-components-styling) for theming default components * Explore [AdaptiveBox](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/adaptive-box-layout) for layout and responsive behavior * Check out [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) for building custom components with independent sizing * See component-specific documentation for size-related features --- # Web Audio API # Web Audio API > Wire AudioUI controls to the native Web Audio API. Covers AudioContext lifecycle, user-gesture unlock, AudioParam automation, and a minimal polysynth example. This guide shows how to bind AudioUI controls directly to the Web Audio API, the native browser audio stack that every higher-level audio library sits on top of. You'll build a small polysynth with a filter, master volume, waveform selector, and playable keys. If you prefer a higher-level library, see the [Tone.js integration](https://cutoff.dev/audio-ui/docs/latest/integrations/tone-js). The patterns here transfer. For a more complete implementation (per-voice filtering, full ADSR, panning, sustain pedal, hardware MIDI input), read the **playground app** source at [`apps/playground-react/app/examples/webaudio/`](https://github.com/cutoff/audio-ui/tree/main/apps/playground-react/app/examples/webaudio) in the AudioUI repository. ## What you'll build A synth with: * A waveform selector (`CycleButton` to oscillator type) * A lowpass filter controlled by two knobs (cutoff + resonance) * A master volume slider * A piano keyboard (`Keys` to note-on / note-off) ## AudioContext lifecycle Browsers suspend `AudioContext` until a user gesture. Create the context early but resume it on a click: ```tsx title="useAudioContext.ts" showLineNumbers import { useEffect, useRef, useState } from "react"; export function useAudioContext() { const ctxRef = useRef(null); const [ready, setReady] = useState(false); useEffect(() => { const ctx = new (window.AudioContext || (window as any).webkitAudioContext)(); ctxRef.current = ctx; return () => { ctx.close(); }; }, []); const start = () => { if (ctxRef.current?.state === "suspended") { ctxRef.current.resume(); } setReady(true); }; return { ctx: ctxRef.current, ready, start }; } ``` ## The synth engine Keep DSP concerns outside React. A plain class that owns the node graph is easier to reason about than state in hooks. Parameters are passed in their real-world units (Hz, Q-factor, linear gain 0-1), matching what the AudioUI controls emit directly. ```ts title="SynthEngine.ts" showLineNumbers export class SynthEngine { private ctx: AudioContext; private filter: BiquadFilterNode; private master: GainNode; private voices = new Map(); private waveform: OscillatorType = "sawtooth"; constructor(ctx: AudioContext) { this.ctx = ctx; this.filter = ctx.createBiquadFilter(); this.filter.type = "lowpass"; this.filter.frequency.value = 1000; this.filter.Q.value = 1; this.master = ctx.createGain(); this.master.gain.value = 0.3; this.filter.connect(this.master); this.master.connect(ctx.destination); } private midiToHz(midi: number) { return 440 * Math.pow(2, (midi - 69) / 12); } noteOn(midi: number) { if (this.voices.has(midi)) return; const osc = this.ctx.createOscillator(); const amp = this.ctx.createGain(); osc.type = this.waveform; osc.frequency.value = this.midiToHz(midi); amp.gain.value = 0; osc.connect(amp); amp.connect(this.filter); osc.start(); amp.gain.setTargetAtTime(0.5, this.ctx.currentTime, 0.01); this.voices.set(midi, { osc, amp }); } noteOff(midi: number) { const voice = this.voices.get(midi); if (!voice) return; voice.amp.gain.setTargetAtTime(0, this.ctx.currentTime, 0.05); voice.osc.stop(this.ctx.currentTime + 0.5); this.voices.delete(midi); } // Accepts Hz directly. The Knob handles log-scale mapping via scale="log". setCutoff(hz: number) { this.filter.frequency.setTargetAtTime(hz, this.ctx.currentTime, 0.02); } setResonance(q: number) { this.filter.Q.setTargetAtTime(q, this.ctx.currentTime, 0.02); } setVolume(gain: number) { this.master.gain.setTargetAtTime(gain, this.ctx.currentTime, 0.02); } setWaveform(wave: OscillatorType) { this.waveform = wave; } } ``` ## Bridging AudioUI to the engine `onChange` on AudioUI controls receives an `AudioControlEvent`. Extract `e.value` and pass it to the engine. Note how the controls work directly in real units (Hz for cutoff, linear for gain) and use `valueFormatter` / `valueAsLabel` to show the current value while the user is interacting: ```tsx title="Synth.tsx" showLineNumbers import { useEffect, useRef, useState } from "react"; import { Knob, Slider, CycleButton, Keys, frequencyFormatter } from "@cutoff/audio-ui-react"; import "@cutoff/audio-ui-react/style.css"; import { SynthEngine } from "./SynthEngine"; import { useAudioContext } from "./useAudioContext"; export default function Synth() { const { ctx, ready, start } = useAudioContext(); const engineRef = useRef(null); const [cutoff, setCutoff] = useState(1000); const [resonance, setResonance] = useState(1); const [volume, setVolume] = useState(0.3); const [waveform, setWaveform] = useState("sawtooth"); useEffect(() => { if (!ctx) return; engineRef.current = new SynthEngine(ctx); engineRef.current.setCutoff(cutoff); engineRef.current.setResonance(resonance); engineRef.current.setVolume(volume); // eslint-disable-next-line react-hooks/exhaustive-deps }, [ctx]); return (
{!ready && } { setWaveform(e.value); engineRef.current?.setWaveform(e.value); }} options={[ { value: "sawtooth", label: "Saw" }, { value: "square", label: "Square" }, { value: "sine", label: "Sine" }, { value: "triangle", label: "Tri" }, ]} label="Wave" /> frequencyFormatter(v)} valueAsLabel="interactive" onChange={(e) => { setCutoff(e.value); engineRef.current?.setCutoff(e.value); }} /> v.toFixed(1)} valueAsLabel="interactive" onChange={(e) => { setResonance(e.value); engineRef.current?.setResonance(e.value); }} /> `${Math.round(v * 100)}%`} valueAsLabel="interactive" onChange={(e) => { setVolume(e.value); engineRef.current?.setVolume(e.value); }} /> { const { note, active } = e.value as { note: number; active: boolean }; if (active) engineRef.current?.noteOn(note); else engineRef.current?.noteOff(note); }} />
); } ``` ## Key patterns ### `onChange` receives an event, not a raw value For continuous and discrete controls (Knob, Slider, Button, CycleButton), `e.value` is the typed value. For `Keys`, `e.value` is `{ note: number; active: boolean }`. Destructure it and branch on `active` for note-on / note-off. ### MIDI to frequency Standard formula: `440 * 2^((midi - 69) / 12)`. MIDI note 69 is A4 = 440 Hz. ### Smooth parameter changes Write to `AudioParam` via `setTargetAtTime(target, startTime, timeConstant)` rather than assigning `.value` directly. The time constant (in seconds) controls how fast the param reaches the target. Values of 0.01-0.05 avoid zippering on knob drags. ### Let AudioUI handle non-linear knob mapping Filter cutoff, frequency, and anything else humans perceive logarithmically should use a log-scale Knob. Pass `scale="log"` and real-world `min` / `max` values (e.g. `min={20} max={10000}` for Hz), and the Knob handles the perceptual mapping internally. Your engine receives values in real units, no manual `Math.pow` conversion needed. Pair this with `valueFormatter={(v) => frequencyFormatter(v)}` to display the value in context (Hz, kHz) and `valueAsLabel="interactive"` to swap the label to the live value while the user is dragging. ### `defaultValue` enables reset When `defaultValue` is set, double-clicking the control resets it to that value. This is the standard DAW/plugin reset gesture. Always set it to a sensible starting value. ### Keep DSP outside React The `SynthEngine` class owns the `AudioContext` and nodes. React only holds state for UI rendering and forwards changes to the engine via `useRef`. That keeps per-frame re-renders from interfering with audio. ## Going further The example above is deliberately minimal. The [playground app's `webaudio` example](https://github.com/cutoff/audio-ui/tree/main/apps/playground-react/app/examples/webaudio) shows a full implementation with: * Per-voice filtering (each note gets its own `BiquadFilter` for independent resonance) * Full ADSR envelope (`linearRampToValueAtTime` for attack/decay, sustain level, exponential release) * Stereo panning via `StereoPannerNode` * Sustain pedal (latch `Button` that defers note-offs until released) * Live parameter updates across active voices (knob drags affect currently-held notes) * Hardware MIDI input via the Web MIDI API It's the canonical reference if you're building a real synth interface with AudioUI. ## Related * [Tone.js integration](https://cutoff.dev/audio-ui/docs/latest/integrations/tone-js), a higher-level synth/effects library * [Audio Parameters](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/audio-parameters), AudioUI's parameter model for strict value validation * [Interaction System](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/interaction-system), keyboard, wheel, touch input --- # Tone.js # Tone.js > Wire AudioUI controls to Tone.js — a higher-level audio framework with synths, effects, and transport. Covers PolySynth, filter routing, and MIDI-to-note-name bridging. [Tone.js](https://tonejs.github.io/) is a higher-level abstraction over the Web Audio API with built-in synths, effects, transports, and musical scheduling. This guide shows how to bind AudioUI controls to a Tone.js polysynth. If you need lower-level control, the [Web Audio API integration](https://cutoff.dev/audio-ui/docs/latest/integrations/web-audio-api) covers the same patterns against the raw browser API. ## Install ```bash npm install tone ``` Tone.js ships its own TypeScript types. ## What you'll build A polysynth driven by AudioUI controls: * `CycleButton` → oscillator waveform * `Knob` → filter cutoff * `Slider` → master volume * `Keys` → polyphonic note-on / note-off ## The synth Build the Tone graph once and keep it in a ref: ```tsx title="Synth.tsx" showLineNumbers import { useEffect, useRef, useState } from "react"; import * as Tone from "tone"; import { Knob, Slider, CycleButton, Keys } from "@cutoff/audio-ui-react"; import "@cutoff/audio-ui-react/style.css"; type Waveform = "sawtooth" | "square" | "sine" | "triangle"; export default function Synth() { const synthRef = useRef(null); const filterRef = useRef(null); const masterRef = useRef(null); const [ready, setReady] = useState(false); const [cutoff, setCutoff] = useState(60); const [volume, setVolume] = useState(60); const [waveform, setWaveform] = useState("sawtooth"); useEffect(() => { const filter = new Tone.Filter(1200, "lowpass"); const master = new Tone.Gain(0.6); const synth = new Tone.PolySynth(Tone.Synth, { oscillator: { type: "sawtooth" }, envelope: { attack: 0.01, decay: 0.1, sustain: 0.6, release: 0.3 }, }); synth.chain(filter, master, Tone.getDestination()); synthRef.current = synth; filterRef.current = filter; masterRef.current = master; return () => { synth.dispose(); filter.dispose(); master.dispose(); }; }, []); // Tone.start() requires a user gesture — browsers suspend AudioContext otherwise const startAudio = async () => { await Tone.start(); setReady(true); }; // Filter cutoff — map Knob's linear 0..100 to 80 Hz .. 10 kHz exponentially const handleCutoff = (e: { value: number }) => { setCutoff(e.value); const min = 80, max = 10000; const hz = min * Math.pow(max / min, e.value / 100); filterRef.current?.frequency.rampTo(hz, 0.02); }; const handleVolume = (e: { value: number }) => { setVolume(e.value); masterRef.current?.gain.rampTo(e.value / 100, 0.02); }; const handleWaveform = (e: { value: Waveform }) => { setWaveform(e.value); synthRef.current?.set({ oscillator: { type: e.value } }); }; // Keys emits { note, active } — convert MIDI to note name for Tone const handleKeys = (e: { value: { note: number; active: boolean } }) => { const { note, active } = e.value; const pitch = Tone.Frequency(note, "midi").toNote(); if (active) synthRef.current?.triggerAttack(pitch); else synthRef.current?.triggerRelease(pitch); }; return (
{!ready && }
); } ``` ## Key patterns ### `Tone.start()` gates audio on user gesture Tone.js internally manages `AudioContext`. Call `Tone.start()` on a user click/tap before triggering sound — otherwise notes are silent. See [Tone's AudioContext docs](https://tonejs.github.io/docs/14.7.39/Context). ### MIDI to note name `Tone.Frequency(midi, "midi").toNote()` converts a MIDI integer (what AudioUI's Keys emits) to a Tone-compatible pitch string (`"C4"`, `"A#3"`). Use this every time you bridge Keys to Tone. Alternative: pass the MIDI number directly to `triggerAttack` as a frequency. Tone accepts both. ### `PolySynth` for polyphonic notes A bare `Tone.Synth` is monophonic. For the keyboard to hold multiple notes, wrap it in `Tone.PolySynth(Tone.Synth, {...})`. Triggering the same pitch twice is idempotent. ### Smooth parameter changes via `rampTo` Tone's `Signal.rampTo(value, time)` is equivalent to the Web Audio `setTargetAtTime` pattern — use it for knob-driven params to avoid zipper noise. ### Effects chain Add effects inline via `synth.chain(...)`. For example, to add reverb and delay: ```ts const reverb = new Tone.Reverb({ decay: 2, wet: 0.3 }); const delay = new Tone.FeedbackDelay({ delayTime: "8n", feedback: 0.3 }); synth.chain(filter, delay, reverb, master, Tone.getDestination()); ``` Bind AudioUI knobs to `reverb.wet.value`, `delay.feedback.value`, etc. ### `Tone.Transport` vs direct triggers For free-form playing (a keyboard), trigger directly. For scheduled sequences (step sequencer, arpeggiator), use `Tone.Transport` with `Tone.Pattern` or `Tone.Sequence`. The keyboard example above uses direct triggers. ## Related * [Web Audio API integration](https://cutoff.dev/audio-ui/docs/latest/integrations/web-audio-api) — lower-level approach * [Audio Parameters](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/audio-parameters) — AudioUI's parameter model * [Keys component](https://cutoff.dev/audio-ui/docs/latest/components/vector/keys) — keyboard API reference --- # AdaptiveBox # AdaptiveBox > Complete reference for AdaptiveBox component, the layout system that powers all AudioUI controls. AdaptiveBox is the layout component that powers all AudioUI controls. It provides a CSS-only layout system for SVG-based controls with optional labels, ensuring responsive behavior without JavaScript overhead. ## Overview AdaptiveBox solves the layout challenge of combining SVG graphics with text labels in a responsive, container-aware way. It uses CSS container queries and aspect-ratio calculations to create a scalable layout system. ### Key Features * **Pure CSS layout**: No ResizeObserver or JavaScript calculations * **Container queries**: Responsive sizing using `cqw`/`cqh` units * **Aspect-preserving scaling**: Maintains component proportions * **Label integration**: Seamless label positioning and alignment * **Performance optimized**: Zero JavaScript overhead for layout ## Architecture AdaptiveBox uses a three-layer structure: 1. **Wrapper**: Container query provider (`container-type: size`) 2. **Aspect Scaler**: Preserves combined aspect ratio (SVG + label) 3. **Content**: SVG and label in a two-row grid ### DOM Structure ```tsx {/* SVG content */} Label Text ``` ## Props Reference ### AdaptiveBox Props | Name | Type | Default | Required | Description | | :--------------- | :------------------------------ | :--------- | :------- | :-------------------------------------------- | | viewBoxWidth | number | - | Yes | Width of the SVG viewBox (W) | | viewBoxHeight | number | - | Yes | Height of the SVG viewBox (H) | | displayMode | "scaleToFit" \| "fill" | scaleToFit | No | How the component scales within its container | | labelMode | "visible" \| "hidden" \| "none" | visible | No | Label display mode | | labelHeightUnits | number | 15 | No | Label height in viewBox units (L) | | minWidth | string | - | No | CSS min-width for the wrapper | | minHeight | string | - | No | CSS min-height for the wrapper | | className | string | - | No | Additional CSS classes | | style | React.CSSProperties | - | No | Additional inline styles | ### AdaptiveBox.Svg Props ```typescript type AdaptiveBoxSvgProps = { viewBoxWidth?: number; // Override from AdaptiveBox (rarely needed) viewBoxHeight?: number; // Override from AdaptiveBox (rarely needed) hAlign?: "start" | "center" | "end"; // Horizontal alignment vAlign?: "start" | "center" | "end"; // Vertical alignment preserveAspectRatio?: string; // SVG preserveAspectRatio (auto-set in fill mode) onWheel?: (e: WheelEvent) => void; // Wheel event handler onMouseDown?: (e: MouseEvent) => void; // Mouse down handler // ... other SVG event handlers }; ``` ### AdaptiveBox.Label Props ```typescript type AdaptiveBoxLabelProps = { position?: "above" | "below"; // Default: "below" align?: "start" | "center" | "end"; // Default: "center" labelMode?: "visible" | "hidden" | "none"; // Override from AdaptiveBox children?: React.ReactNode; // Label content }; ``` ## Display Modes ### scaleToFit (Default) The component scales to fit within its container while preserving aspect ratio. Letterboxing occurs on the non-limiting axis. ```tsx title="ScaleToFit.tsx" showLineNumbers import { AdaptiveBox } from "@cutoff/audio-ui-react"; export default function ScaleToFitExample() { return (
Scale to Fit
); } ``` ### fill The component fills its container completely. The SVG may distort to fill the available space. ```tsx title="Fill.tsx" showLineNumbers import { AdaptiveBox } from "@cutoff/audio-ui-react"; export default function FillExample() { return (
Fill Container
); } ``` ## Label Modes ### visible (Default) Label is rendered and visible. Space is reserved in the layout. ```tsx title="LabelVisible.tsx" showLineNumbers {/* SVG */} Visible Label ``` ### hidden Label space is reserved but the label is not rendered (useful for consistent sizing). ```tsx title="LabelHidden.tsx" showLineNumbers {/* SVG */} Hidden Label ``` ### none No label space is reserved. Component uses SVG-only aspect ratio. ```tsx title="LabelNone.tsx" showLineNumbers {/* SVG */} {/* No AdaptiveBox.Label needed */} ``` ## Label Positioning ### Position (Above/Below) ```tsx title="LabelPosition.tsx" showLineNumbers import { AdaptiveBox } from "@cutoff/audio-ui-react"; export default function LabelPositionExample() { return (
{/* SVG */} Above {/* SVG */} Below
); } ``` ### Alignment (Start/Center/End) ```tsx title="LabelAlignment.tsx" showLineNumbers import { AdaptiveBox } from "@cutoff/audio-ui-react"; export default function LabelAlignmentExample() { return (
{/* SVG */} Start {/* SVG */} Center {/* SVG */} End
); } ``` ## Layout Algorithm ### Step 1: Wrapper Setup The wrapper fills its parent and provides container query units: ```css .wrapper { width: 100%; height: 100%; container-type: size; /* Enables cqw/cqh units */ } ``` ### Step 2: Aspect Calculation The aspect scaler calculates the combined aspect ratio: ``` Aspect Ratio = W / (H + L) ``` Where: * `W` = viewBoxWidth * `H` = viewBoxHeight * `L` = labelHeightUnits ### Step 3: Scaling In `scaleToFit` mode: ```css .aspect-scaler { aspect-ratio: W / (H + L); width: min(100%, calc(100cqh * W / (H + L))); height: auto; } ``` In `fill` mode: ```css .aspect-scaler { width: 100%; height: 100%; } ``` ### Step 4: Grid Layout The scaler uses a two-row grid: ```css .grid-template-rows: H_percent% L_percent%; ``` Label below (default): SVG in row 1, Label in row 2 Label above: Label in row 1, SVG in row 2 ## Alignment ### Scaler Alignment Control how the scaler aligns within the wrapper: ```tsx title="ScalerAlignment.tsx" showLineNumbers {/* SVG */} Aligned ``` Or use `hAlign`/`vAlign` on `AdaptiveBox.Svg`: ```tsx title="SvgAlignment.tsx" showLineNumbers {/* SVG */} Aligned ``` ## Overlays Add HTML content overlays above the SVG: ```tsx title="Overlay.tsx" showLineNumbers import { AdaptiveBox } from "@cutoff/audio-ui-react"; export default function OverlayExample() { return (
50%
With Overlay ); } ``` ## Performance Considerations * **Pure CSS**: No JavaScript calculations for layout * **Container queries**: Browser-optimized responsive sizing * **CSS variables**: Computed once, cached by browser * **No layout shifts**: Dimensions available from first render * **Hardware acceleration**: CSS transforms and aspect-ratio are GPU-accelerated ## Integration with Components All AudioUI components use AdaptiveBox internally. You typically don't need to use AdaptiveBox directly unless building custom controls. However, understanding AdaptiveBox helps when: * Building custom controls with [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) * Creating custom layouts * Understanding component sizing behavior * Debugging layout issues ## Next Steps * Learn about [Default Components Sizing](https://cutoff.dev/audio-ui/docs/latest/customization/default-components-sizing) for component sizing and base units * Explore [Audio Parameters](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/audio-parameters) for parameter-based controls * Check out [Control Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-topics/control-primitives) for building custom controls * See [View System and View Primitives](https://cutoff.dev/audio-ui/docs/latest/advanced-customization/view-system-view-primitives) for custom visualizations --- # Audio Parameters # Audio Parameters Model > Learn how AudioUI's parameter model works, from value systems to scale functions and MIDI integration. AudioUI uses a sophisticated parameter model that bridges the gap between user interface controls and audio processing. This model handles value conversion, quantization, scaling, and MIDI integration automatically. ## Why Parameters Matter Audio applications need to handle three different value domains: 1. **Real values**: What your audio engine uses (e.g., 1000 Hz, -6 dB) 2. **Normalized values**: What the UI uses internally (0.0 to 1.0) 3. **MIDI values**: What external controllers send (0 to 127, or higher resolution) The parameter model automatically converts between these domains, ensuring your UI always reflects the correct quantized state and handles MIDI input correctly. ## The Tripartite Value System AudioUI uses a three-domain value system with MIDI as the pivot point: ### MIDI Value (The Source of Truth) * **Type**: Integer * **Range**: 0 to (2^Resolution - 1) * **Characteristics**: Linear, discrete, quantized * **Role**: Central pivot point for all conversions ### Normalized Value (UI Reality) * **Type**: Float * **Range**: 0.0 to 1.0 * **Characteristics**: Linear with respect to control travel and MIDI values * **Usage**: Used by visual components and host automation ### Real Value (Audio Reality) * **Type**: `number | boolean | string` * **Range**: Defined by parameter type * **Characteristics**: Can be logarithmic, exponential, discrete, or boolean * **Usage**: What your application logic actually uses ## Parameter Types AudioUI supports three parameter types: ### Continuous Parameters Used for variable controls like volume, frequency, pan, etc. ```tsx title="ContinuousParameter.tsx" showLineNumbers import { createContinuousParameter } from "@cutoff/audio-ui-react"; import { Knob } from "@cutoff/audio-ui-react"; import { useState } from "react"; const cutoffParam = createContinuousParameter({ paramId: "cutoff", label: "Cutoff", min: 20, max: 20000, unit: "Hz", scale: "log", defaultValue: 1000, }); export default function ContinuousParameterExample() { const [value, setValue] = useState(1000); return ( setValue(e.value)} /> ); } ``` ### Boolean Parameters Used for on/off controls like mute, solo, bypass. ```tsx title="BooleanParameter.tsx" showLineNumbers import { createBooleanParameter } from "@cutoff/audio-ui-react"; import { Button } from "@cutoff/audio-ui-react"; import { useState } from "react"; const powerParam = createBooleanParameter({ paramId: "power", label: "Power", latch: true, defaultValue: false, }); export default function BooleanParameterExample() { const [value, setValue] = useState(false); return (