Exclusivebeta
Trend Chip <mv-trend-chip>
The tiny “▲ +12.4% vs last week” chip for KPI cards, dashboards, pricing tables and reports: give it the change (value="0.124") or two amounts (from / to) and it prints the signed value through Intl as a percent, percentage points, a plain number, any currency or any unit (“−32 ms”), with an optional period. better="down" makes a fall in churn, latency or cost read as good, and tone is carried by shape as well as color (filled triangle on a soft fill for good, hollow triangle in an outlined chip for bad, thin arrow for neutral, dash for flat), with a tolerance band that counts small moves as about flat. What others miss: screen readers hear one proper sentence (“Up 12.4% vs last week, an improvement”, “Down 0.3 percentage points vs last month, an improvement”) instead of “plus 12 percent up arrow”; sign and rounding are correct (a true minus sign, never “−0.0%”, a change too small for the precision shows “<0.1%” rather than a misleading zero); and it reads without JS: server text inside is kept until the script runs, the value attribute alone already sets tone and arrow in CSS, and a pure describe() export returns the same text, sentence and tone for server rendering.
| Category | Data display |
|---|---|
| Type | Web Component (<mv-trend-chip>) |
| Status | 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
Install
node scripts/add.mjs trend-chip --out ./src/marvelousAI agent with the Marvelous UI MCP server: install_components({ slugs: ["trend-chip"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
Files copied (dependencies included): tokens/tokens.css, core/base.css, core/element.js, components/trend-chip/trend-chip.js, components/trend-chip/trend-chip.css.
Usage
Quick start, the smallest working markup:
<mv-trend-chip value="0.124" period="vs last week"></mv-trend-chip>Canonical markup, to start from and customize with attributes, data-* and CSS variables:
<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 | Type | 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 | Type | 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.