# SvStat
A KPI / metric card: a label, a big value, and an optional delta with an
auto-colored up/down trend, plus slots for an icon and an inline chart.
`SvStat` is the dashboard building block. Give it a `label` and `value`, and
optionally a `delta` - a number auto-signs and infers the trend (green up, red
down), while `invert` flips the coloring for "lower is better" metrics like
error rate or latency. The `icon` and `chart` snippets host a glyph and an
inline [SvSparkline](https://svgrid.com/docs/help/ui-components/sv-sparkline/). Colors come from the grid's `--sg-*`
tokens.
Related: [SvSparkline](https://svgrid.com/docs/help/ui-components/sv-sparkline/) · [SvGauge](https://svgrid.com/docs/help/ui-components/sv-gauge/) · [Range & meters overview](https://svgrid.com/docs/help/ui-components/range/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvStat` starter into your app:
Prefer to see it first? `npx @svgrid/ui try stat` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvStat` ships free in
`@svgrid/grid` (dependency-free):
The examples on this page import from `@svgrid/grid`:
```svelte
```
```ts
import { SvStat } from '@svgrid/grid'
```
## Example
> Live demo: Status & display: alert, stat, timeline, chip, divider, empty - https://svgrid.com/demos/339-status-display/
```svelte
```
## Props
| Prop | Type | Default | Description |
| -------- | -------------------------- | -------- | ---------------------------------------------------------------------- |
| `label` | `string` | required | The metric name, shown above the value. |
| `value` | `string \| number` | required | The headline value (preformat strings like `"$48.2k"`). |
| `delta` | `string \| number` | - | A number auto-signs and infers trend, or pass a preformatted string. |
| `trend` | `up` \| `down` \| `flat` | - | Override the trend inferred from a numeric `delta`. |
| `hint` | `string` | - | Context after the delta (e.g. `"vs last month"`). |
| `invert` | `boolean` | `false` | Treat a downward delta as good (green) - error rate, latency. |
| `icon` | `Snippet` | - | Glyph slot in the card header. |
| `chart` | `Snippet` | - | Inline chart slot, aligned to the end of the footer. |
## Examples
### Trend coloring
A numeric `delta` auto-signs (`+12.4%`) and colors itself - green for up, red for
down. Use `invert` where a drop is the win, and the colors flip:
```svelte
```
### Preformatted delta
Pass a string `delta` when you want full control of the text, and set `trend`
explicitly to drive the arrow and color:
```svelte
```
### Icon and sparkline
Fill the `icon` and `chart` snippets to make a rich tile - a glyph in the header
and a trend line in the footer:
```svelte
{#snippet icon()}{/snippet}
{#snippet chart()}{/snippet}
```
### Dashboard row
`SvStat` cards tile cleanly in a CSS grid for a KPI strip; feed each from your
data and let a numeric `delta` sign and color itself:
```svelte
{#each kpis as k}
{/each}
```
Tip: pass `trend="flat"` to force the neutral gray arrow when a change is not
meaningfully up or down, regardless of the `delta` sign.
## Accessibility
- The trend arrow is `aria-hidden`; the delta text and `hint` carry the meaning
for screen readers.
- Prefer a preformatted, readable `value` (e.g. `"$48.2k"`) so it announces the
way you intend.
- The `icon` slot is decorative and marked `aria-hidden` - keep meaning in the
`label` and `value`.
## See also
- [Feedback overview](https://svgrid.com/docs/help/ui-components/feedback/) - the status and display family at a glance.
- [SvSparkline](https://svgrid.com/docs/help/ui-components/sv-sparkline/) - the inline trend chart for the `chart` slot.
- [SvGauge](https://svgrid.com/docs/help/ui-components/sv-gauge/) - a radial display for a single measured value.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-stat/ . All docs: https://svgrid.com/llms.txt