---
title: MotionMetric
description: Caller-driven metric cards, charts, and composite dashboards.
category: Advanced
status: beta
since: 0.6.3
tags: [motion, metrics, charts, pro]
syncStatus: reviewed
---

## Usage

### All Variants
Each entry in `periods` carries its own `data`; `v-model:period` switches between them.
:::TuffDemoWrapper{demo="MotionMetricDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'
  import { TxMotionMetric } from '@talex-touch/tuffex/motion-metric'

  const period = ref('weekly')
  const periods = [
    { value: 'weekly', label: 'Weekly', data: {
      title: 'Sales analytics', value: 345, target: 500,
      series: [
        { id: 'sales', label: 'Sales', points: [{ label: 'Sep', value: 120 }, { label: 'Oct', value: 225 }] },
        { id: 'earnings', label: 'Earnings', points: [{ label: 'Sep', value: 90 }, { label: 'Oct', value: 180 }] },
      ],
    } },
    { value: 'monthly', label: 'Monthly', data: monthlyData },
  ]
  </script>

  <template>
    <TxMotionMetric v-model:period="period" variant="m-sales-dual" :periods="periods" />
  </template>
---
:::

### Best Practices

- Give every period real `data` and handle update events when controlled; don't relabel a button over the same series.
- The caller owns timer `remaining` / `total`, monitoring state, noise readings, and message delivery; `running` expresses intent only.
- Keep readouts, barcode scores, ring progress, and charts consistent with `target` / `min` / `max` / `unit`. Credit-score composites default to 300–850, which you can override.
- Give series, metrics, groups, and cells stable IDs, real labels, and full units; missing points are never filled in.
- Localize with `labels`, `formatValue`, and a licensed avatar slot. Respect reduced motion; add no polling or permanent animation.

## API Reference

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `MotionMetricVariant` | `m-progress-piano` | Catalog, composite, or original interaction ID. |
| `interaction` | `MotionMetricInteraction` | `progress-indicator-piano` | Interaction branch, used only by `animated-metric-card`. |
| `data` | `MotionMetricData` | `—` | The caller's dataset. |
| `series` | `MotionMetricSeries[]` | `—` | Overrides the current dataset's series. |
| `metrics` | `MotionMetricReadout[]` | `—` | Overrides the current dataset's readouts. |
| `status` | `string` | `—` | Caller status; never read as business success. |
| `period` | `string` | `First period` | Current period, bound with `v-model:period`. |
| `periods` | `MotionMetricPeriod[]` | `—` | Period options, each with its own data. |
| `filterStyle` | `'pills' \| 'select'` | `Source-appropriate` | Native pills or a native select. |
| `activeIndex` | `number` | `0` | Controlled chart, matrix, or step index. |
| `modelValue` | `number` | `data.value / data.threshold` | Numeric readout; the threshold in alert layouts. |
| `range` | `[number, number]` | `[data.min ?? 30, data.max ?? 120]` | Noise range bounds; emits input, never measures audio. |
| `running` | `boolean` | `false` | Timer running state; starts no internal clock. |
| `message` | `string` | `Empty` | Feedback draft. |
| `disabled` | `boolean` | `false` | Disables native inputs and action events. |
| `animated` | `boolean` | `true` | Enables value and gauge motion, still gated by visibility and reduced motion. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `md` | Spacing and numeral size. |
| `labels` | `Partial<MotionMetricLabels>` | `English defaults` | Overrides control and empty-state strings. |
| `formatValue` | `(value, unit?) => string` | `Number with up to 2 decimals + unit` | Formats display only; chart data is untouched. |

### Events

| Event | Payload | Description |
|---|---|---|
| `update:period` | `string` | Fires when a period is chosen. |
| `update:activeIndex` | `number` | Fires when a chart point, matrix cell, or step is chosen. |
| `update:modelValue` | `number` | Fires when progress, noise value, or alert threshold changes. |
| `update:range` | `[number, number]` | Fires when the noise bounds change. |
| `update:running` | `boolean` | Start or pause intent; there is no internal clock. |
| `update:message` | `string` | Fires when the feedback draft changes. |
| `select` | `{ id: string, index: number }` | Fires when a data point is chosen; chart points have an empty `id`. |
| `filter` | `{ groupId: string, period: string }` | Fires when a dashboard group switches period. |
| `action` | `string` | `details`, `share`, `more`, `add`, `resume`, or `all`. |
| `send` | `string` | Sends the trimmed, non-empty message. |

### Slots

| Slot | Scope | Description |
|---|---|---|
| `header` | `{ data }` | Custom heading area. |
| `avatar` | — | A licensed avatar from the caller. |
| `preview` | `{ data }` | Content preview in the feedback layout. |
| `footer` | `{ data }` | Source, unit, or update time. |

### Types

| Type | Fields | Description |
|---|---|---|
| `MotionMetricData` | `title, description, value, target, min, max, unit, previous, rank, status, remaining, total, threshold, columns, metrics, series, groups, cells, weekdays, steps, profiles, messages` | No business defaults; `remaining` / `total` are seconds, and gauge `target` defaults to 100. |
| `MotionMetricSeries` | `id, label, points, unit?, tone?` | Independent series; points have `label` / `value`, plus optional `description`, `tone`, and sleep-stage `level` (0–100). |
| `MotionMetricReadout` | `id, label, value, unit?, previous?, target?, description?, status?, tone?, grade?` | Numeric or text readout; `grade` serves credit reports. |
| `MotionMetricGroup` | `id, label, value?, target?, unit?, columns?, cells?, metrics?, series?, period?, periods?` | Named sub-layout; sales, finance, and credit groups can carry their own periods, controlled when `period` is set. |
| `MotionMetricCell` | `id, label, value, description?, selected?` | Activity intensity or calendar day; selection emits id and index. |
| `MotionMetricStep` | `id, label, value, status?` | Relative segment width and caller step state. |
| `MotionMetricProfile` | `id, name, initials?, status, detail?, value?, segments?, flight?` | `flight` holds label/from/to/departure/arrival/progress (0–100); no avatar URL is bundled. |
| `MotionMetricMessage` | `id, author, text, time?` | Caller messages; `send` neither appends nor claims delivery. |
| `MotionMetricPeriod` | `value, label, data` | Selected data merges over base `data`; top-level `series` / `metrics` / `status` win. |

#### Group IDs

| Variant | Group IDs | Description |
|---|---|---|
| `cache-stats-card / cacheable-bandwidth-cost` | `bandwidth` | `group.value` / `unit` is the cacheable amount; `group.metrics` is the cached and non-cacheable split. |
| `network-telemetry` | `Any ID` | Each group is a named activity matrix. |
| `sales-dashboard` | `analytics, target` | Paired bars and segmented sales target. |
| `credit-score-cards` | `report, utilization, history` | Graded rows, balance/limit, and score history. |
| `finance-dashboard` | `savings, credit, expenses, assets` | Pixel savings, barcode, stacked expenses, and filterable asset allocation. |
| `marketing-cards` | `channels, campaign` | Channel allocation and chart/readout split. |
| `health-cards` | `goals, period, hydration, workout, steps, sleep, heart, target` | Daily rings, cycle dots, charts, sleep stages, and weekly target. |
| `system-metrics-card` | `Any ID` | Each group has quantiles and its own chart; top-level `metrics` are the error breakdown. |
| `course-progress-card` | `Any ID` | Training chart and attendee readouts. |

#### MotionMetricLabels

Keys and defaults of `labels`, exported as `MOTION_METRIC_DEFAULT_LABELS`:

```ts
{
  period: 'Period', empty: 'No data for this period', details: 'View details', share: 'Share', more: 'More actions',
  scrubber: 'Select a data point', current: 'Current', target: 'Target', remaining: 'Remaining',
  low: 'Low', high: 'High', minimum: 'Minimum', maximum: 'Maximum', threshold: 'Threshold',
  start: 'Start', pause: 'Pause', message: 'Message', send: 'Send', all: 'See all', resume: 'Resume',
  analysis: 'Analysis', average: 'Average',
}
```

### CSS Variables

| Variable | Purpose |
|---|---|
| `--tx-mm-pad` | Root padding. |
| `--tx-mm-gap` | Section spacing. |
| `--tx-mm-number` | Numeral size. |
| `--tx-chart-categorical-1..6` | Series colors. |
| `--tx-chart-grid-line` | Chart reference grid. |
| `--tx-color-*`, `--tx-text-color-*`, `--tx-fill-color-*`, `--tx-bg-color`, `--tx-border-color-*` | Shared semantic theme. |

## Variants and Source Mapping

### Catalog Entries

| Catalog ID | Interaction | Capability |
|---|---|---|
| `m-cache-bandwidth` | `cacheable-bandwidth-cost` | Cached / non-cacheable allocation, total, and cost |
| `m-net-matrix` | `network-telemetry-matrix` | Finality readouts and independent network matrices |
| `m-progress-piano` | `progress-indicator-piano` | 28 piano keys and numeric goal input |
| `m-server-step` | `server-performance-step-bars` | Staircase columns with bright top caps |
| `m-overview-scrubber` | `overview-bar-scrubber-card` | Striped columns, active point, and scrubber tooltip |
| `m-sales-dual` | `sales-analytics-dual-bars` | Sales / earnings paired bars and unit target |
| `m-sales-arc` | `sales-target-segmented-arc` | Listed / delivered segmented half-circle |
| `m-sales-radial-dash` | `sales-overview-radial-dashboard` | Rank banner, radial goal, and two readouts |
| `m-credit-barcode` | `credit-score-barcode-meter` | 42-stroke credit meter with period dropdown |
| `m-mono-stock` | `mono-stock` | Monochrome stock curve, period data, and hover values |
| `m-users-pill` | `users-growth-pill-progress` | Star/profile header and selectable pill bars |
| `m-views-wave` | `views-hourly-wave-chart` | Hourly wave, actual average, and period filtering |
| `m-mono-heatmap` | `mono-heatmap` | Caller-owned 28-day grayscale activity matrix |
| `m-timer-prep` | `timer-preparation-segmented` | Remaining time, selected stage, and segmented steps |
| `m-noise-level` | `noise-decibel-level` | Signal bars, current input, and paired range controls |

### Source Capabilities

Paths are relative to upstream `src/components/metrics/`; `MOTION_METRIC_SOURCE_MAP` exports the full mapping.

| Source | Variant | Capability |
|---|---|---|
| `AnimatedMetricCard.tsx` | `animated-metric-card` | 29 interaction branches; no universal fallback card |
| `Budget.tsx` | `budget` | Three-row 64-column budget matrix and details event |
| `CacheStatsCard.tsx` | `cache-stats-card` | Query/cache readouts and bandwidth breakdown |
| `CourseProgressCard.tsx` | `course-progress-card` | Course ring, resume/all actions, training bars, and attendees |
| `CreditScoreCards.tsx` | `credit-score-cards` | Score half-circle, graded report, utilization, and history curve |
| `FeedbackCard.tsx` | `feedback-card` | Caller preview, editable message, send event, and message list |
| `FinanceDashboard.tsx` | `finance-dashboard` | Savings pixels, credit barcode, stacked expenses, and asset filter |
| `Growth.tsx` | `growth` | Three pixel-height growth columns |
| `GrowthCalendar.tsx` | `growth-calendar` | Selectable growth pills and caller calendar |
| `HealthCards.tsx` | `health-cards` | Daily rings, cycle dots, hydration, workout, steps, sleep stages, heart rate, and weekly target |
| `MarketingCards.tsx` | `marketing-cards` | Channel allocation and campaign chart/readout split |
| `NetworkTelemetry.tsx` | `network-telemetry` | Summary statistics and per-network pixel matrices |
| `NoiseCards.tsx` | `noise-cards` | Separate noise readings and paired range controls |
| `OverviewChart.tsx` | `overview-chart` | Monthly striped columns and selected readout |
| `ProgressIndicator.tsx` | `progress-indicator` | 36-key progress, comparison, and numeric input |
| `PromptsCard.tsx` | `prompts-card` | 30-segment prompt quota meter |
| `RealTimeAlerts.tsx` | `real-time-alerts` | Budget bars and editable threshold line; emits input only |
| `RunningStatsCard.tsx` | `running-stats-card` | Distance/duration and daily bars including zero days |
| `SalesDashboard.tsx` | `sales-dashboard` | Four summary stats, paired sales bars, and segmented target |
| `SalesOverview.tsx` | `sales-overview` | Rank banner, 12-segment goal, and two stats |
| `SavingsCards.tsx` | `savings-cards` | Savings progress, add event, target, and transaction columns |
| `ServerPerformance.tsx` | `server-performance` | Capped staircase performance columns |
| `StatusCards.tsx` | `status-cards` | Profiles, activity/sleep timelines, and flight progress |
| `StockChartCard.tsx` | `stock-chart-card` | Supplied stock series with first/last delta |
| `SystemMetricsCard.tsx` | `system-metrics-card` | Latency/lag charts, quantiles, and error breakdown |
| `TimerCard.tsx` | `timer-card` | Remaining seconds, stage tooltip, steps, and running event |
| `UserMetrics.tsx` | `user-metrics` | Four audience statistics and a views/average wave |
| `UsersChartCard.tsx` | `users-chart-card` | Audience area, secondary readouts, and details event |
| `VisitorsChartCard.tsx` | `visitors-chart-card` | Two independent visitor curves and multi-series tooltip |

### AnimatedMetricCard Interactions

The catalog's 15 interactions plus the 14 below make up all 29 branches. Pass one directly as `variant`, or use `variant="animated-metric-card"` with `interaction`.

| Interaction | Capability |
|---|---|
| `mono-revenue` | Revenue curve |
| `mono-credit` | Credit ring and tier |
| `mono-wallet` | Balance and inflow/outflow |
| `mono-savings` | Savings target and progress |
| `mono-activity-ring` | Concentric independent activity goals |
| `mono-users` | Active users and regional badges |
| `mono-kfactor` | Referral multiplier ring |
| `mono-latency` | Quantiles and latency polyline |
| `mono-bandwidth` | Speed half-circle and latency/loss |
| `mono-server` | Independent CPU/RAM rings and node/heap data |
| `mono-progress` | Build ring, steps, and caller status |
| `mono-radar` | Incident half-circle and caller alert counts |
| `mono-timer-arc` | Remaining-time ring and start/pause event |
| `mono-timer-ring` | Independent focus/break concentric rings |

## Overview

- The component queries no network, audio, health, financial, or monitoring service, generates no data, and starts no timer; the caller updates `series`, `metrics`, `status`, `remaining`, and the rest.
- Missing data shows an empty state, never fixed readings.
- Charts expose keyboard-operable data-point scrubbers; the noise bounds natively limit each other, so they never cross.
- Value and gauge motion stops offscreen, in hidden documents, in inactive KeepAlive instances, and under reduced motion.

## Technologies

- Reuses SVG/D3 charts, `TxStatCard`, `TxSlider`, `TxInput`, `TxButton`, and `TxTextMorph`.
- Upstream: the Metrics components at [Amicro commit 43c29ce](https://github.com/Subhan-code/Amicro--Micro-transitions-/tree/43c29ce9cdd16459e3eab4992381b8d35b38776a), MIT, Copyright (c) 2026 SYED  SUBHAN UDDIN.
- Source: `packages/tuffex/packages/components/src/motion-metric/`.