Tarjeta de KPI independiente para dashboards de aplicaciones, configurada solo con atributos: etiqueta con un icono opcional, una cifra que se anima contando (number-ticker), su variación respecto a un valor anterior (trend-chip), un sparkline de histórico (chart) o un indicador hacia un máximo (progress en anillo), una nota y un pie, además de un tamaño compacto para cuadrículas densas, como ocho tarjetas de retrasos de pago en una misma pantalla de finanzas.
Agente de IA con el servidor MCP de Marvelous UI: install_components({ slugs: ["metric-tile"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
Name of the metric. Shown above the figure and used as the tile's accessible name (role=group).
value
number
The figure. Changing it rolls the number to the new value and recomputes the change and the gauge. Without it the tile shows “-” and says “No data”.
unit
string
Text after the figure, smaller and muted (days, ms, invoices).
format
decimal | currency | percent | compact
decimal
Intl style of the figure, as in number-ticker. percent expects percentage points (42 = 42%).
currency
ISO 4217 code
USD
Currency for format=currency.
decimals
number
(inferred from value)
Fraction digits of the figure.
compact
boolean
Compact notation, combinable with currency ($72.4K).
locale
BCP 47
nearest lang, else en-US
Formatting locale for the figure, the gauge and the sparkline. The change follows the nearest lang, like trend-chip.
previous
number
Value of the previous period. With value, it drives the change chip (relative change by default).
change
number
A change computed elsewhere, used instead of previous (a fraction for percent and points: 0.124 = +12.4%).
change-format
percent | points | number | currency | ISO 4217 code | Intl unit
percent
How the change is computed and printed (trend-chip's format). points with format=percent compares the two percentages in points; an Intl unit such as day or millisecond prints the difference in that unit.
better
up | down | neutral
up
Which direction is good: colors and words of the change. Use down for delays, costs, churn.
period
string
What the change is measured against (vs last month).
history
comma-separated numbers
Past values, oldest first, drawn as a sparkline (two values at least). An empty item is a gap.
history-labels
comma-separated strings
Point 1, Point 2…
Labels of the history values, read in the sparkline's data table.
chart-type
area | line | bar
area
Sparkline style.
max
number
Shows a ring gauge of value between min and max, with the percentage in its center.
min
number
0
Lower bound of the gauge.
note
string
A muted line under the figures (target, context, last update).
animate
view | none
view
view: the figure counts up and the sparkline draws in when the tile scrolls into view. none: everything shows at once.
data-size
regular | compact
regular
compact: smaller text and padding, the figure and the change share a line, and the sparkline or the gauge sits on the right, for dense grids of tiles.
Properties
Name
Tipo
Default
Description
strings
object
MvMetricTile.strings
Translatable text merged over the defaults: empty (“-”), noValue (“No data”), gauge (“{percent} of {max}”, also {value}), chart (“{label}, history”) and point (“Point {n}”). Nested change and chart objects are handed to the trend chip's and the sparkline's own strings. Can be set before the element is defined.
ticker / chip / chart
Element | null
Read-only: the inner mv-number-ticker, mv-trend-chip and mv-chart, for fine tuning (tile.chip.tolerance = 0.005). null before the first connection.
percent
number | null
Read-only: where value stands between min and max (0 to 100), or null without a gauge.
label / value / previous / change / history / max …
string | number
Every attribute is mirrored as a property (camelCase: changeFormat, historyLabels, chartType); setting one updates the tile at once, even before the element is defined.
Methods
Name
Description
render()
Syncs every part with the attributes now (rarely needed: changes already do it).
Events
Name
Description
mv-end
Bubbles from the inner number-ticker when the figure finishes counting (detail.value).
Content structure
Name
Description
icon
A child with slot="icon" (an svg, an img, an icon element) moves to the left of the label. It is decorative: the tile hides it from screen readers.
footer
Children with slot="footer" (a link, a button, a timestamp) go to a footer row under a hairline.
CSS classes
Name
Description
mv-metric-tile-body / -main
Generated: the figures column and, beside it, the gauge.
mv-metric-tile-head / -icon / -label
Generated: the label row.
mv-metric-tile-figure / -unit / -empty
Generated: the figure (an mv-number-ticker), its unit, and the “-” shown without a value.
mv-metric-tile-change
Generated: the mv-trend-chip.
mv-metric-tile-gauge
Generated: the ring gauge (a .mv-progress-ring with role=meter).
The tile is a role=group named by its label, so a screen reader announces “Revenue, group” and then reads, in order: the figure (number-ticker's hidden final value: the counting digits are aria-hidden and never read in bursts) with its unit, the change as one whole sentence from trend-chip (“Up 12.4% vs last month, an improvement”, “Down 5 days vs last month, an improvement” with better="down"), the gauge as role=meter named by the label with a spoken value (“72% of $100K”), the sparkline as chart's labelled group with its visually hidden data table, then the note and the footer. The icon is aria-hidden. Without a value the figure shows “-” and says “No data”. Updates are silent (no live region): a refreshing dashboard never interrupts the reader. Nothing is focusable except what you put in the footer; the compact sparkline is not interactive either. Meaning never depends on color: the change carries a glyph and words, and data-tone / data-dir (good, bad, neutral; up, down, flat) are exposed on the tile for styling only. Reduced motion: the figure, the gauge and the sparkline show their final state at once. Forced colors: the tile keeps a CanvasText frame, the chip and the chart switch to their own system-color styles. Known limits: the gauge animates on first display, not on scroll into view; the change chip reads its locale from the nearest lang rather than the locale attribute; tolerance and digits of the change are set on tile.chip.