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.

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

NameTypeDefaultRequiredDescription
valuestring | number—YesCurrent value of the control
onChange(event: AudioControlEvent<string | number>) => void—NoHandler for value changes
labelstring—NoLabel displayed below the component
frameWidthnumber—YesWidth of a single frame in the filmstrip (pixels)
frameHeightnumber—YesHeight of a single frame in the filmstrip (pixels)
frameCountnumber—YesTotal number of frames in the filmstrip sprite sheet
imageHrefstring—YesURL to the sprite sheet/filmstrip image
orientation"vertical" | "horizontal"verticalNoOrientation of the filmstrip (frames stacked vertically or horizontally)
frameRotationnumber0NoOptional frame rotation in degrees
adaptiveSizebooleanfalseNoWhether the component stretches to fill its container
size"xsmall" | "small" | "normal" | "large" | "xlarge"normalNoSize of the component
parameterDiscreteParameter—NoAudio Parameter definition (Model). If provided, overrides options/label from ad-hoc props
optionsArray<{ value: string | number; label?: string; midiValue?: number }>—NoArray of option definitions (strict mode)
childrenReact.ReactNode—NoOptionView 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.

Basic Usage

FilmStripDiscreteControl requires a filmstrip sprite sheet image and frame dimensions. Use OptionView children to define the discrete options:

BasicFilmStripDiscrete.tsx

Modes of Operation

FilmStripDiscreteControl supports three modes of operation:

Ad-Hoc Mode (Children Only)

Model inferred from OptionView children:

AdHocFilmStripDiscrete.tsx

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:

StrictModeFilmStripDiscrete.tsx

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.

HybridModeFilmStripDiscrete.tsx

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:

FrameDimensions.tsx

Orientation

Control whether frames are stacked vertically or horizontally:

Orientation.tsx

Frame Rotation

Rotate the entire filmstrip container:

FrameRotation.tsx

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 and their size attribute:

FilmStripDiscreteSizing.tsx

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.

FilmStripDiscreteAdaptiveSize.tsx

Common Use Cases

Traffic Light (Multiple States)

TrafficLight.tsx

Waveform Selector

WaveformSelector.tsx

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