Options vs OptionView

Discrete controls in AudioUI (such as CycleButton, ImageRotarySwitch, and FilmStripDiscreteControl) can define their set of choices in two ways: through option definitions (the parameter model) and through OptionView children (the view). This page explains the distinction and when to use each.

Model vs View

The library separates two concerns:

• Option definitions (the model): Data that describes which values exist, their labels, and optional MIDI mapping. This drives value handling, cycling order, quantization, and MIDI integration. It does not define what is rendered (icons, styled text, custom components).
• OptionView (the view): React elements that provide what to render for each option. Each OptionView has a value (matching an option) and children (any ReactNode). It does not define the parameter structure; it only supplies visual content.

You can use option definitions alone (the component will fall back to rendering labels), OptionView children alone (the component infers the option set from the children), or both together (definitions for the model, OptionView for custom visuals matched by value).

When to Use OptionView

For basic use of discrete components, and especially when using ad-hoc props (no parameter prop), prefer OptionView children. In that case the option set is inferred from the OptionViews: each <OptionView value="..."> contributes one option, and the same children are used for display. This is intuitive (similar to HTML <select> and <option>) and easy to extend (replace text with icons or custom components without touching the parameter model).

Use the options prop or a full parameter when you need explicit parameter structure: data-driven option lists, MIDI property mapping, or integration with the full Audio Parameters model. See CycleButton for the four modes (ad-hoc with children, options prop, strict parameter, hybrid).

When to Use the options Prop or Parameter

Use option definitions (via the options prop or a discrete parameter from createDiscreteParameter) when:

• Options come from external or dynamic data (e.g. from an API, a parameter registry such as one built on WebMIDI, or a backend such as a Tauri command).
• You need explicit midiValue per option for MIDI CC or high-resolution mapping.
• You are building against the full parameter model and want a single source of truth for value handling, labels, and MIDI.

The discrete parameter model is designed to align with the MIDI 2.0 Property Exchange schema for controller descriptions. In particular, the structure of option definitions (value, label, optional midiValue) is compatible with the valueSelect typeHint used to describe controls that have a fixed set of selectable values. This allows the same option set to drive both the UI and PE-compliant controller metadata.

Option Definitions Do Not Provide Visual Content

The options prop (and the options array inside a discrete parameter) defines parameter structure only. Each entry typically has:

• value: the real value (string or number)
• label: a string (used for fallback display or accessibility when no OptionView is provided)
• midiValue (optional): integer for MIDI mapping

These fields do not accept React nodes or custom visuals. To show icons, formatted text, or custom components for each option, use OptionView children and match them by value. When both are present, the component uses the option definitions for behavior and OptionView children for rendering (when a matching OptionView exists).

OptionView Does Not Define the Parameter Model

OptionView components only supply what to render for a given value. They do not specify labels for automation, MIDI mapping, or the authoritative list of options. When you use only OptionView children (no options prop and no parameter), the component infers the list of options from the children. That is the recommended pattern for simple, ad-hoc discrete controls.

Summary

Concern	Option definitions (options prop / parameter)	OptionView children
Purpose	Parameter structure (values, labels, MIDI)	Visual content (ReactNodes)
Defines	Which options exist; cycling, quantization, MIDI	What is displayed per option
Preferred for	Data-driven or parameter-model integration	Basic use; ad-hoc props; custom visuals
Inferred when omitted	Yes, from OptionView children (when no options/parameter)	No; component falls back to option label

For a full treatment of the parameter model, see Audio Parameters. For component-level details and modes, see CycleButton.