Sampler Keyboard
sampler-keyboardControlsThe piano keyboard that shows what a sampler instrument maps.
$ pnpm dlx shadcn@latest add @pluginui/core-sampler-keyboardInstall
Copies the source into your project. Anything it depends on comes with it. Run this in your React project with shadcn initialized; no registry configuration is needed.
Pulls in
Install using the registry URL
$ pnpm dlx shadcn@latest add https://pluginui.com/r/core-sampler-keyboard.jsonUsage
Connect the documented props to your application or host.
import { SamplerKeyboard } from "@/components/ui/sampler-keyboard"
<SamplerKeyboard
startNote={36}
octaves={4}
width="100%"
height={140}
coverage={zones.map((zone) => ({ low: zone.lowKey, high: zone.highKey }))}
held={activeNotes}
onNoteOn={noteOn}
onNoteOff={noteOff}
/>About Sampler Keyboard
A playable keyboard drawn from an instrument's own facts. It supports exact mapped-key coverage, muting every unmapped key individually rather than by bounding box (as in Kontakt and Decent Sampler keybed presentations), per-group coverage in distinct colours for kit mappings, authored key-colour ranges from instrument formats, and a playable range that mutes keys the instrument cannot sound. It also supports strike velocity from press position, glissando, a held map that lights keys from the engine's active notes, and computer-keyboard input. These shared behaviors belong to the piano keyboard alongside every other keyboard in the kit. The sampler module face and Studio sampler editor draw the same control.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| coverage | { low, high, color? }[] | — | Exact mapped-key ranges. Mapped keys get the coverage paint; every other key is muted. |
| groupCoverage | SamplerKeyRange[][] | — | Per-group ranges, each painted a distinct zone colour. Supersedes coverage. |
| colorRanges | SamplerColorRange[] | — | Authored key colourings, hex ARGB as instrument formats write them. |
| playableRange | { low, high } | null | — | Keys the instrument can sound; null mutes the whole keybed. Superseded by coverage. |
| coverageColor | string | — | CSS colour for the mapped-key paint. Defaults to the classic blue. |
| …PianoKeyboardProps | — | startNote, octaves, held, onNoteOn, onNoteOff, labels and the rest of the piano keyboard's contract. |
Interaction
- Drag with pointer capture, so the gesture keeps tracking past the edge of the control.
- Shift while dragging for a fine pass; release it mid-gesture and coarse tracking resumes.
- Double-click resets to
defaultValue. - Arrow keys step normally, Shift+arrow steps finely, PageUp/PageDown jump by ten, Home/End go to the extremes.
- Proper
sliderandswitchroles with livearia-valuetext, so a screen reader announces the formatted value rather than the raw number. - The scroll wheel adjusts the value while the pointer is over the control; stepped ranges move at least one declared step per notch by default.