MusicStaff

MusicStaff reads a short series as a melody, so its shape lands in one look: each value is a note on a five-line staff, pitch (vertical position) is the value, and left-to-right is time. Pitch is the only channel, so there are no clefs, stems, beams, or bar lines. The read is in steps (nine to thirteen positions), so exact values steer to Sparkline with a label. Two adjacent equal values are spaced along the time axis and never dodged vertically, because moving a note vertically would change its pitch.

Install

import { MusicStaff } from "@microcharts/react/music-staff";// weeks — real values under “Sample data” below<MusicStaff data={weeks} title="Sprint melody" />

const weeks = [3, 5, 4, 8, 6, 9, 7, 11];

Try it

import { MusicStaff } from "@microcharts/react/music-staff/interactive";// weeks — real values under “Sample data” below<MusicStaff  data={weeks}/>

const weeks = [3, 5, 4, 8, 6, 9, 7, 11];

When to use it

Use it for a weekly-rhythm read in a sentence, the shape of a sprint or short series in a cell, or a per-channel melody in a tab. For exact values use Sparkline with a label; skip it for long series (over sixteen points) and for trends where the exact slope matters.

Sizing

Variants

Ledger mode is the default: a note above or below the staff sits on a hairline ledger tick and keeps its true pitch, rather than being clipped. mode="staff" is for dense cells where ledger lines would collide with a neighbour; there, out-of-range pitches clamp to the nearest staff line or space, trading visual precision for a collision-free cell. The accessible summary is the same either way, since it describes the raw values, not the clamped pixel positions.

Edge cases

A single value draws one note and no contour line, since a melody needs at least two notes to have a shape. An all-null series draws the bare staff with no notes at all, and the accessible name falls back to describeSeries's own no-data phrasing. With a locale, the trailing label="last" value follows that locale's own grouping and decimal marks.

Four homes

Accessibility

MusicStaff reuses Sparkline's natural-language summary verbatim. For [3, 5, 4, 8, 6, 9] that is "Trending up 200%. Range 3 to 9. Last value 9." The interactive entry steps the notes with ←/→ and announces each as "Point 3 of 6: 4."

The interactive entry follows the shared interaction contract: arrow keys rove between units on both axes, Home and End jump to the ends, and a click, tap, Enter or Space selects a unit — pinning its readout so it survives blur, until you select it again, press Escape, or press outside the chart. On touch, a tap pins and a drag scrubs.

Props

Plus the shared grammar — data, domain, color, title, summary, format — and the layout props (width, height, className, style) that every chart accepts. Interactive entries also share animate and live, and — wherever a chart has more than one navigable unit — onActive, onSelect, selectedIndex and defaultSelectedIndex; and — wherever the chart shows a hover value — readout. See the shared grammar.