Exclusivobeta
Trend Chip <mv-trend-chip>
El diminuto chip “▲ +12,4 % vs. la semana pasada” para tarjetas de KPI, paneles, tablas de precios e informes: dale la variación (value="0.124") o dos importes (from / to) y muestra el valor con signo mediante Intl como porcentaje, puntos porcentuales, número simple, cualquier moneda o cualquier unidad (“−32 ms”), con un periodo opcional. better="down" hace que una bajada del churn, la latencia o el costo se lea como positiva, y el tono se transmite con la forma además del color (triángulo relleno sobre fondo suave para lo bueno, triángulo hueco en un chip con contorno para lo malo, flecha fina para lo neutro, guion para lo estable), con una banda de tolerancia que cuenta los movimientos pequeños como prácticamente estables. Lo que a otros se les escapa: los lectores de pantalla oyen una frase correcta (“Sube un 12,4 % respecto a la semana pasada, una mejora”, “Baja 0,3 puntos porcentuales respecto al mes pasado, una mejora”) en lugar de “más 12 por ciento flecha arriba”; el signo y el redondeo son correctos (un auténtico signo menos, nunca “−0,0 %”, y una variación demasiado pequeña para la precisión muestra “<0,1 %” en lugar de un cero engañoso); y se lee sin JS: el texto del servidor que contiene se conserva hasta que se ejecuta el script, el atributo value por sí solo ya fija el tono y la flecha en CSS, y una exportación pura describe() devuelve el mismo texto, la misma frase y el mismo tono para el renderizado en servidor.
| Categoría | Visualización de datos |
|---|---|
| Tipo | Web Component (<mv-trend-chip>) |
| Estado | beta |
| Keywords | exclusive, light, trend, delta, change, kpi, dashboard, percent, badge, intl, ssr, a11y |
When to use
- A KPI card or dashboard tile shows how a figure moved since the previous period
- A report or pricing table lists changes where some metrics are better when they go down, like churn, cost or latency
- A change badge must not rely on color alone and must be read as a sentence by screen readers
- Server-rendered pages should print the change in HTML and keep it readable before or without JavaScript
Avoid when
- The change must be judged against inflation, a benchmark or peers rather than against zero → use Real Terms instead
- A whole section of headline figures with counters and sparklines is needed → use Stats instead
- The number itself should count up or roll when it changes → use Number Ticker instead
Instalación
node scripts/add.mjs trend-chip --out ./src/marvelousAgente de IA con el servidor MCP de Marvelous UI: install_components({ slugs: ["trend-chip"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
Archivos copiados (dependencias incluidas): tokens/tokens.css, core/base.css, core/element.js, components/trend-chip/trend-chip.js, components/trend-chip/trend-chip.css.
Uso
Inicio rápido, el marcado mínimo que funciona:
<mv-trend-chip value="0.124" period="vs last week"></mv-trend-chip>Marcado de referencia: parte de él y personalízalo con atributos, data-* y variables CSS:
<div id="mv-tc-demo" style="display:grid;gap:1.25rem;width:min(100%,52rem);margin-inline:auto">
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(11.5rem,1fr));gap:.75rem">
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">Revenue</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">$48,210</p>
<mv-trend-chip id="mv-tc-revenue" value="0.124" period="vs last week">+12.4% vs last week</mv-trend-chip>
</section>
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">Churn rate</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">2.1%</p>
<mv-trend-chip from="0.024" to="0.021" format="points" better="down" period="vs last month"></mv-trend-chip>
</section>
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">p95 latency</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">214 ms</p>
<mv-trend-chip from="182" to="214" format="millisecond" better="down" period="vs last week"></mv-trend-chip>
</section>
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">Active users</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">12,480</p>
<mv-trend-chip value="-0.036" period="vs last week"></mv-trend-chip>
</section>
</div>
<div style="display:flex;flex-wrap:wrap;align-items:center;gap:.75rem;font-size:.8125rem;color:var(--mv-fg-muted)">
<button class="mv-button" data-variant="outline" data-size="sm" id="mv-tc-refresh">Load next week</button>
<span>Screen readers hear: <q id="mv-tc-said" style="color:var(--mv-fg)"></q></span>
</div>
<div class="mv-table-wrap">
<table class="mv-table">
<caption>September report. Plain variant; costs and refunds are lower-is-better.</caption>
<thead><tr><th>Metric</th><th data-align="end">September</th><th data-align="end">Change vs August</th></tr></thead>
<tbody>
<tr><td>Support cost</td><td data-align="end">$17,950</td><td data-align="end"><mv-trend-chip data-variant="plain" id="mv-tc-cost" from="18400" to="17950" format="currency" better="down"></mv-trend-chip></td></tr>
<tr><td>Sign-ups</td><td data-align="end">1,204,410</td><td data-align="end"><mv-trend-chip data-variant="plain" from="1204300" to="1204410"></mv-trend-chip></td></tr>
<tr><td>Refund rate (±0.5% counts as flat)</td><td data-align="end">1.9%</td><td data-align="end"><mv-trend-chip data-variant="plain" id="mv-tc-refunds" value="0.003" better="down"></mv-trend-chip></td></tr>
<tr><td>Uptime</td><td data-align="end">99.95%</td><td data-align="end"><mv-trend-chip data-variant="plain" from="0.9995" to="0.9995" format="points"></mv-trend-chip></td></tr>
<tr><td>Headcount</td><td data-align="end">45</td><td data-align="end"><mv-trend-chip data-variant="plain" from="42" to="45" format="number" better="neutral"></mv-trend-chip></td></tr>
</tbody>
</table>
</div>
</div>
<script type="module">
const root = document.getElementById("mv-tc-demo");
const revenue = root.querySelector("#mv-tc-revenue");
const said = root.querySelector("#mv-tc-said");
root.querySelector("#mv-tc-cost").digits = 0;
root.querySelector("#mv-tc-refunds").tolerance = 0.005;
const weeks = ["0.124", "-0.048", "0.0004", "0"];
let i = 0;
const show = () => customElements.whenDefined("mv-trend-chip").then(() => { said.textContent = revenue.state.label; });
root.querySelector("#mv-tc-refresh").addEventListener("click", () => {
i = (i + 1) % weeks.length;
revenue.value = weeks[i];
show();
});
show();
</script>API
Attributes
| Name | Tipo | Default | Description |
|---|---|---|---|
value | number | The change. For percent and points it is a fraction (0.124 = +12.4%, 0.003 = +0.3 pts); for number, currency and units it is the difference itself. Takes precedence over from / to. | |
from / to | number | Or give the previous and current amounts: percent computes (to − from) / |from| (from = 0 gives no comparison), the other formats use to − from. For points, give rates as fractions (0.024 → 0.021). | |
format | percent | points | number | currency | ISO 4217 code | Intl unit | percent | How the change is printed, always through Intl: “+12.4%”, “−0.3 pts”, “+140”, “−$450.00” (currency = USD, or a code such as EUR), or a unit such as millisecond, kilobyte or hour (“−32 ms”). |
period | string | What the change is measured against, shown after the chip and placed in the sentence: “vs last week”. | |
better | up | down | neutral | up | Which direction is an improvement. down: a fall reads as good (churn, cost, latency). neutral: no judgment, only the direction. |
lang (inherited) | BCP 47 | Number locale from the nearest [lang] ancestor, else en-US. | |
data-variant | plain | Styling hook: colored text and glyph without the pill, for dense tables and inline copy (bad changes get a dotted underline as a second cue). | |
data-dir / data-tone | up | down | flat | none / good | bad | neutral | Set by the component (for styling). A server can write them too, from describe(). |
Properties
| Name | Tipo | Default | Description |
|---|---|---|---|
tolerance | number | 0 | A change whose size is at or below this (same units as value: 0.005 = half a percent) is about flat: dash glyph, neutral tone, and a sentence that still says which way it moved (“About flat vs last month, up 0.3%”). |
digits | number | 1 for percent and points, the currency's own for money, up to 1 otherwise | Fraction digits. Percent and points always print exactly this many, so every chip on a page rounds the same way. |
strings | object | MvTrendChip.strings | Translatable text, merged over the defaults: whole sentences upGood, upBad, up, downGood, downBad, down, flat, nearUp, nearDown, none with {value} and {period} placeholders, plus under (“<{value}”), underLong (“less than {value}”), points, pointsLong and empty (“-”). |
state | { dir, tone, text, period, label, change } | Read-only: the current result, including the spoken sentence (label) and the raw change. | |
value / from / to / format / period / better | string | Mirror the attributes; changes re-render at once. All can be set before the element is defined. |
Methods
| Name | Description |
|---|---|
describe({ value, from, to, format, period, better, tolerance, digits, locale, strings }) | Named export (and static MvTrendChip.describe): pure and server-safe, returns { dir, tone, text, period, label, change }, the exact visible text and sentence the element renders. |
render() | Re-render now (rarely needed: attribute and property changes already do it). |
Content structure
| Name | Description |
|---|---|
(text) | Server-rendered fallback, read as is before the script loads; replaced by the parts once it runs. Without value or from / to, the text is left untouched. |
.mv-trend-chip-value / -period / -label | Or render the final parts on the server (from describe()): they are adopted in place, so nothing shifts on upgrade. |
CSS classes
| Name | Description |
|---|---|
mv-trend-chip-value | The pill: glyph (::before, a CSS mask) and signed value; aria-hidden. |
mv-trend-chip-period | The muted period text; aria-hidden (it is part of the sentence). |
mv-trend-chip-label | The visually hidden sentence read by screen readers (mv-sr-only). |
CSS variables
| Name | Default | Description |
|---|---|---|
--mv-trend-chip-good | var(--mv-success) | Good tone. |
--mv-trend-chip-bad | var(--mv-danger) | Bad tone. |
--mv-trend-chip-neutral | var(--mv-fg-muted) | Neutral and flat tone. |
--mv-trend-chip-font-size | var(--mv-text-xs) | Text size (the glyph scales with it). |
--mv-trend-chip-radius | var(--mv-radius-full) | Pill corner radius. |
--mv-trend-chip-gap | 0.4em | Space between the pill and the period. |
Accessibility
Plain inline content, no role and no tab stop. The visible pill and period are aria-hidden and a visually hidden span carries one complete sentence built from a whole-sentence template (never glued fragments): “Up 12.4% vs last week, an improvement”, “Down 32 ms vs last week, an improvement” with better="down", “Up 3” with better="neutral", “Unchanged vs yesterday”, “About flat vs last month, up 0.3%” inside the tolerance, “Up less than 0.1% vs yesterday, an improvement” for tiny changes, and “No comparison available” when the change cannot be computed. The number in the sentence is unsigned (the word carries the direction), so nothing reads “plus” or “minus” or “up arrow”. Updates are silent (no live region): a dashboard refreshing its tiles never interrupts the reader, and the text is only written when it actually changes. Meaning never depends on color alone (WCAG 1.4.1): direction is the glyph's orientation, good is a filled triangle, bad is a hollow triangle in an outlined chip (plus a dotted underline in the plain variant), neutral is a thin arrow and flat is a dash. Text colors are mixed toward the foreground for contrast on the tinted pill, in light and dark themes. Forced colors: the glyph is drawn in CanvasText, the chip gets a border, dashed when the change is bad. The glyph's turn when the direction flips uses the motion tokens and is removed under prefers-reduced-motion and [data-motion="reduce"]. Before or without JS, server-rendered text inside the element is read as written, and CSS already derives tone and direction from the value attribute.