PianoKeys

Piano keyboard rendered as SVG. This is not a complete app; it is meant to be used as a component in webapps.

See the demo application.

Install with npm

You can install PianoKeys as an npm package in your project:

npm i @jesperdj/pianokeys

Using PianoKeys

Create a HTML div element in your HTML or using JavaScript that will hold the keyboard.

<div id="container"></div>

Then in your script, create an instance of PianoKeys.Keyboard, passing it the container element.

import PianoKeys from '@jesperdj/pianokeys';

const container = document.getElementById('container');
const keyboard = new PianoKeys.Keyboard(container);

This will render a keyboard corresponding to a regular 88-key piano, starting at the note A0 and ending at C8.

Rendering a partial keyboard

The constructor of PianoKeys.Keyboard takes an optional second parameter, which is an object with options. You can render a partial keyboard by setting the lowest and highest properties in the options object to set the lowest and highest note (key). These are specified as a note name with an octave number, for example 'A0', 'Bb4', 'D#6'.

Note: The keyboard always starts and ends with a white key. If you specify a note name that corresponds to a black key, the next lower or higher white key will be used.

Example:

const keyboard = new PianoKeys.Keyboard(container, {
    lowest: 'C2',
    highest: 'C5'
});

Using custom colors

You can set the following properties in the options object to specify custom colors:

• keyStroke - stroke style for the outline of keys
• whiteKeyFill - fill style for the white keys
• blackKeyFill - fill style for the black keys

Example:

const keyboard = new PianoKeys.Keyboard(container, {
    lowest: 'C2',
    highest: 'C5',
    keyStroke: '#444',
    whiteKeyFill: 'black',
    blackKeyFill: 'white'
});

Highlighting keys

To highlight keys, call fillKey() on the keyboard. Example:

keyboard.fillKey('C3');
keyboard.fillKey('Bb3');
keyboard.fillKey('Eb4');
keyboard.fillKey('G4');

The fillKey() function optionally takes a second parameter to set the fill style to use for that key instead of the default highlight style.

keyboard.fillKey('C3', 'red');

Call clearKey() to unhighlight a key.

keyboard.clearKey('C3');

If you want to use a custom highlight fill style but you don't want to specify it in each call to fillKey(), then you can set the default highlight fill style by adding the following properties to the options that you pass to the constructor:

• whiteKeyHighlightFill - default highlight fill style for white keys
• blackKeyHighlightFill - default highlight fill style for black keys

Example:

const keyboard = new PianoKeys.Keyboard(container, {
    lowest: 'C2',
    highest: 'C5',
    keyStroke: '#444',
    whiteKeyFill: 'black',
    whiteKeyHighlightFill: 'yellow',
    blackKeyFill: 'white',
    blackKeyHighlightFill: 'orange'
});

Customizing key geometry

A number of options are available to customize the way the keys are drawn.

• keysAreRounded - set to false if you want rectangular keys
• keyWidth - specify the width of each white key. Default is 24
• blackKeyWidth - specify the width of each black key. Default is 14
• blackKeyHeightRatio - modify the height of black keys, expressed as a percentage of white key height. Valid range is 5% to 100%, expressed as a float (0.05 to 1.0)
• spacing - specify a visual gap between white keys. Even values work best. Default is 0
• keyStrokeWidth - specify the width of any applied stroke. Default is 2

Example:

const keys = new PianoKeys.Keyboard(document.getElementById('keys'), {
    lowest: 'C3',
    highest: 'C5',
    whiteKeyFill: '#666E6F',
    blackKeyFill: '#181818',
    whiteKeyHighlightFill: '#D1D3D4',
    keysAreRounded: false,
    keyWidth: 28,
    blackKeyWidth: 28,
    blackKeyHeightRatio: 0.55,
    spacing: 6,
    keyStrokeWidth: 0,
});

keys.fillKey('D3');
keys.fillKey('E3');

Responding to key presses

You can set a custom function to be called when a key on PianoKeys is clicked.

The function receives the MouseEvent as well as an object containing a note number and string representation of the note (eg: Bb3 for Bb in the 3rd octave)

Example:

const keyboard = new PianoKeys.Keyboard(container);

keyboard.setOnKeyClick((e, keyInfo) => {
    console.log(`key pressed - note number: ${keyInfo.note} ${keyInfo.name}`);
});