Basic Usage

Need to display a piano diagram with some highlighted notes?

Installation


pnpm add @music-ui/piano


npm install @music-ui/piano


yarn add @music-ui/piano

Usage

The @music-ui/piano package exports an initPiano function.

By default it selects all [data-piano] element inside the document:


<div data-piano></div>

Setup code:


import { initPiano } from "@music-ui/piano";
import "@music-ui/piano/styles.css";
 
initPiano();

Output:

You can pass a custom selector or collection of elements.


<div class="my-piano"></div>
<div class="my-piano"></div>

Setup code:


import { initPiano } from "@music-ui/piano";
import "@music-ui/piano/styles.css";
 
// via selector string
initPiano({ selection: ".my-piano" });
 
// via actual DOM selection
initPiano({ selection: document.querySelectorAll(".my-piano") });

Output:

Note highlight

You can highlight specific notes via the data-notes attribute:


<div data-piano data-notes="C4 E4 G4 B4"></div>

Setup code:


import { initPiano } from "@music-ui/piano";
import "@music-ui/piano/styles.css";
 
initPiano();

Output:

To avoid position ambiguity, always append the octave after the note (i.e. use scientific pitch notation ).

Multiple voices

You can highlight different group of notes in different colors, e.g. when you need to separate left and right hand content.

Separate the note groups via a comma, like:


<div data-piano data-notes="C3 C4, E4 G4 C5"></div>

Setup code:


import { initPiano } from "@music-ui/piano";
import "@music-ui/piano/styles.css";
 
initPiano();

Output:

Render options

Configuration can be passed via data attributes:


<div
  data-piano
  data-start-octave="2"
  data-octaves="4"
  data-with-final-c="false"
  data-show-octaves
></div>

Setup code:


import { initPiano } from "@music-ui/piano";
import "@music-ui/piano/styles.css";
 
initPiano();

Output:

The following data attributes are supported:

Attribute	Type	Description
`data-octaves`	`number`	The amount of rendered octaves
`data-start-octave`	`number`	The first octave being rendered
`data-with-final-c`	`boolean`	Renders a final C key after the last octave
`data-show-octaves`	`boolean`	Displays the octave number on every C note
`data-notes`	`string`	The notes to be highlighted
`data-note-labels`	`string`	The note labels

Check the complete initPiano API reference for more details.

Appearance customization

All the sizes and colors are configurable via CSS variables.

The defaults are found in the imported CSS file .

You can override them in your style files.