<mq-piano>

Piano keyboard with realistic key geometry. Configurable range, accurate or centered black key positioning, preserve-ratio for real-world proportions. Stylable via ::part() and CSS custom properties. Named slots for per-key annotations.

← Back to index

Install

npm install @hsablonniere/musiq
import '@hsablonniere/musiq/mq-piano';

API

Attributes / Properties

Attribute Property Type Default Description
start-note startNote string C3 First note of the keyboard range. If a black key is specified, the white key before it is included
end-note endNote string E4 Last note of the keyboard range. If a black key is specified, the white key after it is included
mode mode 'accurate' | 'centered' accurate Black key positioning: accurate uses real piano geometry, centered centers them between white keys
preserve-ratio preserveRatio boolean false Lock aspect ratio to real piano proportions (the unconstrained dimension is derived from the constrained one)

Slots

Slot Description
note-{name}{octave} Per-note content — e.g. note-C3, note-Fs4, note-Db3. Black keys expose both enharmonic names. Use s for sharp (♯) since # is not valid in slot names.

CSS Custom Properties

Property Default Description
--mq-piano-border-color #000 Base color for all borders (outer + inner)
--mq-piano-border-width 1px Base width for all borders (outer + inner)
--mq-piano-border-color-outer falls back to border-color Color of the outer border around the keyboard
--mq-piano-border-color-inner falls back to border-color Color of borders between keys
--mq-piano-border-width-outer falls back to border-width Width of the outer border around the keyboard
--mq-piano-border-width-inner falls back to border-width Width of borders between keys

CSS Parts

Part Description
key All keys (white and black)
key-white White keys only
key-black Black keys only

Range — default

Without start-note or end-note, the keyboard covers the default range C3 → E4.

Range — full piano

A standard acoustic piano: 88 keys from A0 to C8.

A0 — C8 · 52 white keys · 36 black keys

Range — custom

2 octaves, C3 → C5

Range — single bound

Only one end of the range provided, the other is inferred.

start-note="G2" (end inferred)

end-note="G5" (start inferred)

Mode — centered

With mode="centered", every white key has the same width and black keys are perfectly centered between their neighbors.

mode="accurate" (default)

mode="centered"

Style — borders

Width and color via CSS custom properties.

1px gray

6px red

Style — ::part()

Harpsichord (inverted colors)

Style — ::part()

Neon theme

Slots — annotations

Label each key with note names via named slots.

C / Do C♯
Do♯ D / Ré D♯
Ré♯ E / Mi F / Fa F♯
Fa♯ G / Sol G♯
Sol♯ A / La A♯
La♯ B / Si C / Do C♯
Do♯ D / Ré D♯
Ré♯ E / Mi

Slots — colored dots

C major chord highlighted

1
3
5
1
3
5

Layout — preserve-ratio

Locks the keyboard to realistic piano proportions.

Width constrained: width: 600px — height derived from ratio