@diatonic/piano

Diatonic Piano

Interactive SVG piano as a React component.

Reference

• Installation
• Static Piano
• Pressed and Highlighted keys
• Styling
  • Default
  • CSS Variables
  • Advanced CSS Targeting
• Interactivity
• Accessibility

Installation

npm install @diatonic/piano

Then import the component:

import { Piano } from "@diatonic/piano";

function App() {
  return <Piano />;
}

Static Piano

By default, the piano will expand to fill its container. If you place the <Piano> tag inside a div with fixed width, you'll get a simple, static piano:

<Piano />

The following props can be set to modify the SVG representation static piano:

Prop	Description	Default
octaves	Number of octaves	2
width	Width of the <svg> element	'100%'
height	Height of the <svg> element	'100%'
preserveAspectRatio	Attribute for <svg> element (details)	'xMinYMin meet'

Pressed and Highlighted keys

Two props can be used to set a key as pressed or highlighted. There are no real differences between the two, but it can be used to separate permanently pressed keys from the key currently being hovered, or to mark a chord and a scale at the same time. Highlighted keys are lighter in the default style. The two props are:

Prop	Description	Default
pressed	Keys will be pressed	[]
highlighted	Keys will be highlighted	[]

As an example, you can press F4, A4, and C#5 to highlight an F augmented chord:

<Piano pressed={["F4", "A4", "C#5"]} />

Internally, the component uses kamasi to figure out which notes to highlight. The component also accepts kamasi objects as input. So if your cool friends want to improvise over a D minor blues scale, you're just a single line from knowing which keys to use:

import { scale } from "kamasi";

<Piano highlighted={scale("D blues minor")} />;

Styling

Default

The piano includes built-in default colors via SVG presentation attributes, so it works out-of-the-box with sensible default colors:

import { Piano } from "@diatonic/piano";

<Piano />

CSS Variables

Import the default stylesheet to override variables:

import "@diatonic/piano/styles.css";

:root {
  /* White keys */
  --piano-key-diatonic-fill: #f0f0f0;
  --piano-key-diatonic-pressed-fill: #4caf50;
  --piano-key-diatonic-highlighted-fill: #81c784;
  --piano-key-diatonic-stroke: #333;

  /* Black keys */
  --piano-key-chromatic-fill: #333;
  --piano-key-chromatic-pressed-fill: #4caf50;
  --piano-key-chromatic-highlighted-fill: #81c784;
  --piano-key-chromatic-stroke: #000;

  /* Global */
  --piano-key-stroke-width: 4;
}

All available CSS variables:

Variable	Description	Default
--piano-key-diatonic-fill	White key default color	#f7f5f0
--piano-key-diatonic-pressed-fill	White key pressed color	#e07858
--piano-key-diatonic-highlighted-fill	White key highlighted color	#eca088
--piano-key-chromatic-fill	Black key default color	#4a423c
--piano-key-chromatic-pressed-fill	Black key pressed color	#c04838
--piano-key-chromatic-highlighted-fill	Black key highlighted color	#b86850
--piano-key-diatonic-stroke	White key border color	#c0b8b0
--piano-key-diatonic-pressed-stroke	White key pressed border	#b8624c
--piano-key-diatonic-highlighted-stroke	White key highlighted border	#b8624c
--piano-key-chromatic-stroke	Black key border color	#4a423c
--piano-key-chromatic-pressed-stroke	Black key pressed border	#4a423c
--piano-key-chromatic-highlighted-stroke	Black key highlighted border	#4a423c
--piano-key-stroke-width	Border width for all keys	2

Advanced CSS Targeting

For maximum control, target CSS classes and data attributes directly:

Classes:

Class	Description
.diatonic-piano	Top <svg> component
.diatonic-piano-octave-<n>	The <g> tag grouping all keys within one octave
.diatonic-piano-key	The <path> tag for all keys
.diatonic-piano-key-<pitchclass>	All keys of this pitch class (e.g., C, Cs)
.diatonic-piano-key-<pitch>	Specific key (e.g., C4, Cs4)

Data attributes:

Attribute	Values	Description
data-key-type	diatonic, chromatic	White or black key
data-pressed	true, false	Whether the key is pressed
data-highlighted	true, false	Whether the key is highlighted

Example: Rainbow keys

/* Using a parent class ensures proper specificity */
#rainbow-piano {
  --piano-key-stroke-width: 2;
}
#rainbow-piano .diatonic-piano-key-G4 {
  fill: #f898a4;
}
#rainbow-piano .diatonic-piano-key-A4 {
  fill: #fcda9c;
}
#rainbow-piano .diatonic-piano-key-B4 {
  fill: #f7faa1;
}
#rainbow-piano .diatonic-piano-key-C5 {
  fill: #b4f6a4;
}
#rainbow-piano .diatonic-piano-key-D5 {
  fill: #9be0f1;
}
#rainbow-piano .diatonic-piano-key-E5 {
  fill: #a2aceb;
}

<div id="rainbow-piano">
  <Piano />
</div>

Interactivity

Enable direct interaction with piano keys using the interactive prop and event handlers:

Prop	Description
interactive	Enables clicking, hovering, and keyboard navigation of keys
onPress	Called with (note, event) when a key is clicked or activated with Enter
onHighlightStart	Called with (note, event) when pointer enters a key or the key receives focus
onHighlightEnd	Called with (note, event) when pointer leaves a key or the key loses focus

Each event handler receives two parameters:

• note - The note string (e.g., 'C4')
• event - The original DOM event (MouseEvent, KeyboardEvent, PointerEvent, or FocusEvent)

The component is fully stateless and relies on the parent to update pressed and highlighted props. This gives you complete control over the piano's behavior and enables synchronization with other components.

Using React hooks, you only need a few lines of code. The following is the complete App.js file showing two pianos where the second mirrors the first, transposed a perfect fifth:

import { useState } from "react";
import { Piano } from "@diatonic/piano";
import { NoteList } from "kamasi";

function App() {
  const [pressed, setPressed] = useState(new NoteList());
  const [highlighted, setHighlighted] = useState(new NoteList());

  return (
    <div style={{ width: "300px" }}>
      <Piano
        interactive={true}
        pressed={pressed}
        highlighted={highlighted}
        onPress={(n) => setPressed((note) => note.toggle(n))}
        onHighlightStart={(n) => setHighlighted(new NoteList([n]))}
        onHighlightEnd={() => setHighlighted(new NoteList())}
      />
      <Piano
        pressed={pressed.transpose("P5")}
        highlighted={highlighted.transpose("P5")}
      />
    </div>
  );
}

export default App;

See kamasi's documentation for more manipulation you can do, or check the Diatonic web app for inspiration.

Accessibility

The component automatically adapts its ARIA roles and labels based on usage:

• Display mode (default): role="img" with aria-label="Piano - Pressed keys: ..." or "Piano - No pressed keys"
• Interactive mode (interactive or keyboardShortcuts): role="group" containing interactive buttons

The aria-label always includes the currently pressed keys for screen reader users, regardless of interactivity mode.

The component offers two complementary modes of keyboard access:

Prop	Description	Default
interactive	Enables keyboard navigation with <Tab> and <Enter>	false
keyboardShortcuts	Enables QWERTY keyboard shortcuts to play notes	false

Direct key navigation (interactive={true}): Users can traverse through keys in chromatic order (left to right) using Tab, and activate a key with Enter. This works for all visible keys on the piano. The onPress event fires whether the key is clicked or activated with Enter, and onHighlightStart/onHighlightEnd work for both pointer hover and keyboard focus.

QWERTY shortcuts (keyboardShortcuts={true}): Turns the keyboard into a virtual piano. Keys Q-U play octave 3, A-J play octave 4, and Z-M play octave 5 (white keys). Hold Shift to play the black key (sharp) for any key. The onPress event fires with the played note when a keyboard shortcut is used.

Both modes can be enabled simultaneously, and both trigger the same onPress event handler.