custom-piano-keys

A web component for creating custom HTML elements that depict piano keys.

2 live demos available here and here

Features

Custom-piano-keys is a stand-alone vanilla JS web component that does not use shadow DOM.

Following component attributes are configurable:

• element height
• octave width
• number of octaves
• stroke width
• black key height and width
• marked keys
• mark color, shape, diameter and shift

Including the component to an HTML file

1. Import polyfill, this is not needed for modern browsers:

   <script src="https://cdnjs.cloudflare.com/ajax/libs/custom-elements/1.3.2/custom-elements.min.js"></script>

2. Import custom element:

   <script defer src='custom-piano-keys.min.js'></script>

3. Start using it!

   <custom-piano-keys> </custom-piano-keys>

Including the component from NPM

1. Install and import polyfill, this is not needed for modern browsers:

   See https://www.npmjs.com/package/@webcomponents/custom-elements

2. Install custom-piano-keys NPM package:

   npm i custom-piano-keys

3. Import custom element:

   import 'custom-piano-keys'

4. Start using it:

   var pianokeys = document.createElement("custom-piano-keys")
   pianokeys.setAttribute("marked-keys", "1 5 8")
   document.body.appendChild(pianokeys)

Attributes

Name	Type	Description	Unit / Values	Default value
oct-count	Number	Number of octaves	Zero or positive integer	1
height	Number	Element height	Element height in pixels	100
oct-w-factor	Number	Octave width factor	Factor producing the width from element height	1.5
stroke-w	Number	Stroke width	0 - 100 percents of element height	2
b-key-h	Number	Black key height	0 - 100 percents of element height	60
b-key-w	Number	Black key width	0 - 100 percents of white key width	50
marked-keys	String	Marked keys	Space separated list of integers*	N/A
mark-color	String/Hex	Mark color	Color keyword / 3 digit hex / 6 digit hex**	red
mark-shape	String	Mark shape	circle / rect	circle
mark-diameter	Number	Mark diameter	0 - 100 percents of white key width	40
b-key-mark-shift	Number	Black key mark shift	1 - 100 percents of black key height	50
w-key-mark-shift	Number	White key mark shift	1 - 100 percents of the white key stub height	50

*Valid values for marked-keys are integers from 1 to 96. Setting a new value will remove the previous marks.

**Setting color to black will display black marks on white keys and white marks on black keys

Methods

Keys can be marked directly by calling the setMarkedKeys method of the custom element instance.

Method has a single argument: an array of integers. Valid values in the array are integers from 1 to 96.

Marks can be removed by providing an empty array as an argument.

Keys can also be marked by setting the marked-keys attribute value. Using setMarkedKeys method is an alternative way to set marks on keys by using an array instead of string.

Usage example:

var pianokeys = document.createElement("custom-piano-keys")
pianokeys.setMarkedKeys([1,5,8])
document.body.appendChild(pianokeys)

Removing the marks:

pianokeys.setMarkedKeys([])

License

Copyright (c) 2019 Jussi Utunen

Licensed under the MIT License