score-card

Overview

The <score-card> component is the atom of dashboards. It packages a metric tile — title, headline number, optional change indicator, sparkline, description, and icon — into a single composable element that degrades gracefully without JS or CSS.

Score-card is the enhanced form of the semantic stat figure documented at /docs/patterns/data/stats/. Use the pattern when you need a no-JS recipe; use the component when you want consistent layout, theme-driven trend coloring, drill-down affordance, and skeleton loading.

Basic Examples

Minimal use only requires title and value slots. Add change, icon, and a tone attribute to grow the tile into a full KPI card.

Sparkline composition

The sparkline slot accepts any sized element. The slot reserves a fixed height via --score-card-sparkline-height (default 40px) and clips overflow, so the chosen renderer is sized predictably regardless of internal content.

chart-wc with data-size="sparkline" (recommended)

For data-driven trend tiles, compose with <chart-wc> in sparkline mode. The chart strips axes, gridlines, labels, title, legend, and tooltip and fits the slot's reserved height (default 40px). Same component, same data API, no extra wrapper — and the underlying <table> data source still ships an accessible fallback.

Style the trend by overriding --chart-series-1 per trend value — the sparkline shape inherits the colour automatically:

Inline SVG (lightest option, no chart bundle)

If you don't want to ship the optional charts bundle just for tiles, an inline <svg> works the same way. Style with currentColor so it inherits the trend tone via the parent score-card.

chart-wc full chart (for taller trend cards, 120px+)

Drop the data-size="sparkline" attribute and bump the slot height to render a full chart with axes, tooltip, and legend.

Drill-down (link-wrapping)

To make a tile clickable, wrap it in an anchor. The wrapping <a> receives keyboard focus and click — no synthetic key handling, no role override, no tabindex juggling. The whole tile becomes a single accessible link.

When score-card upgrades, it walks ancestors looking for the nearest <a href>. If found, it sets the :state(interactive) hook so component CSS can apply hover and active affordances.

Shadow CSS can't reach the wrapping anchor, so add this partner light-DOM rule once in your stylesheet to apply hover and focus affordances to the tile:

Note: the :state(interactive) hook is set once on upgrade. If you move a score-card into or out of an anchor at runtime, the state won't re-sync — wrap or unwrap before the element connects.

Loading skeleton

Set the loading attribute while data is in flight. Slotted content stays in the DOM so it doesn't reflow on completion; the value, change, and sparkline regions are visually replaced by a shimmer. The animation respects prefers-reduced-motion and falls back to a flat muted background.

Slots

Per VB convention, content goes in slots and state goes in attributes. The component is intentionally unopinionated about what fills each slot — pass an SVG, canvas, or chart-wc into the sparkline slot; pass any inline element into value when <data> doesn't fit.

Attributes

Internal state hooks

Score-card exposes CustomStateSet entries for CSS targeting via :state():

CSS Tokens

Static fallback

Before upgrade — and when JS is unavailable — score-card renders its slotted children inline. The recommended fallback structure is the same semantic figure pattern documented at /docs/patterns/data/stats/, so consumers get a fully readable metric without the tile chrome:

Accessibility

• Semantic native elements throughout. Score-card adds no ARIA roles — meaning comes from the slotted <figure>, <figcaption>, <data>, and <small> structure.
• Trend is never carried by color alone. Change indicators include the + or − sign and a direction word in the copy.
• Drill-down uses a real anchor. Focus, click activation, right-click menus, and middle-click "open in new tab" all work natively.
• Reduced motion respected. The loading skeleton's shimmer animation falls back to a static muted background under prefers-reduced-motion.

Related