Keys

A responsive and interactive piano keyboard component with configurable number of keys, note highlighting, and multiple styling modes.

The Keys component provides a responsive and interactive piano keyboard visualization. It shares the same layout and accessibility as other vector components; see the Vector introduction.

  • Flexible configuration: Variable number of keys (1-128), different starting positions, octave transposition
  • Note highlighting: Visual feedback for active notes via notesOn prop
  • Multiple styling modes: theme-based, classic ivory/ebony, and inverted classic
  • Interactive control: Optional onChange callback for key press/release events
  • Full theming support: color, roundness customization (in theme mode)

Props

NameTypeDefaultRequiredDescription
nbKeysnumber61NoNumber of keys on the keyboard (1-128)
startKey"A" | "B" | "C" | "D" | "E" | "F" | "G"—NoStarting note name (A-G). Default 'C' for 61 keys, 'A' for 88 keys
octaveShiftnumber0NoOctave transpose index. Positive values shift notes up by that many octaves, negative values shift down
notesOn(string | number)[][]NoArray of notes that should be highlighted. Notes can be specified as strings (e.g., 'C4', 'F#5') or MIDI note numbers (e.g., 60 for C4)
keyStyle"theme" | "classic" | "classic-inverted"themeNoKey styling mode. 'theme' uses theme colors, 'classic' uses ivory/ebony colors, 'classic-inverted' inverts the classic colors
onChange(event: AudioControlEvent<{ note: number; active: boolean }>) => void—NoCallback triggered when a key is pressed or released. Only active if this prop is provided.
colorstring—NoComponent primary color - any valid CSS color value (used in theme mode)
roundnessnumber—NoRoundness for component corners (normalized 0.0-1.0)
adaptiveSizebooleanfalseNoWhether the component stretches to fill its container
size"xsmall" | "small" | "normal" | "large" | "xlarge"normalNoSize of the component
displayMode"scaleToFit" | "fill"scaleToFitNoLayout mode for the control
onClickReact.MouseEventHandler—NoClick event handler
classNamestring—NoAdditional CSS classes
styleReact.CSSProperties—NoAdditional inline styles

Basic Usage

The Keys component can be used as a simple visualization or as an interactive control:

BasicKeys.tsx

Number of Keys

Configure the number of keys on the keyboard (1-128):

NumberOfKeys.tsx

Starting Position

Control which note the keyboard starts with:

StartingPosition.tsx

Octave Transposition

Use the octaveShift prop to transpose the keyboard up or down by octaves:

OctaveShift.tsx

Note Highlighting

Highlight active notes using the notesOn prop. Notes can be specified as strings (note names) or MIDI note numbers:

Using Note Names

NoteNames.tsx

Using MIDI Note Numbers

MIDINotes.tsx

Mixing Note Names and MIDI Numbers

MixedNotes.tsx

Interactive Note Highlighting

Update the highlighted notes based on user interaction:

InteractiveNotes.tsx

Key Styling Modes

The Keys component supports three styling modes:

Theme Mode

The default mode uses theme colors (from the color prop or global theme):

ThemeMode.tsx

Classic Mode

Classic piano style with ivory white keys and ebony black keys:

ClassicMode.tsx

Classic Inverted Mode

Inverted classic style with ebony white keys and ivory black keys:

ClassicInvertedMode.tsx

Note:

In classic and classic-inverted modes, active keys always use the theme color for visual feedback, regardless of the key style.

Theming

Vector components share common theming features; see Theming Features in the Vector introduction for an overview. The Keys component supports theming through the color and roundness props:

Color Customization

In theme mode, customize the color of active keys:

KeysColor.tsx

Roundness

Control the roundness of the key corners:

KeysRoundness.tsx

Adaptive Sizing

The Keys 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:

KeysSizing.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.

Interaction

The Keys component becomes interactive when you provide the onChange prop:

InteractiveKeys.tsx

The onChange callback receives an event with:

  • value.note: The MIDI note number (0-127)
  • value.active: Whether the note is being pressed (true) or released (false)
  • normalizedValue: The normalized value (0.0-1.0)
  • midiValue: The MIDI note number

Common Patterns

Full Piano Keyboard

A standard 88-key piano keyboard:

FullPiano.tsx

Compact Keyboard

A compact 25-key keyboard for mobile or space-constrained interfaces:

CompactKeyboard.tsx

MIDI Monitor

A keyboard that highlights notes received from MIDI input. In a real app you would connect this to MIDI input; here it shows a static example:

MIDIMonitor.tsx

Chord Display

Display a chord by highlighting specific notes:

ChordDisplay.tsx

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

MIDIKeyboard.tsx

Piano Roll Display

PianoRoll.tsx

Compact Keyboard Control

CompactKeyboardControl.tsx

Next Steps