Spotlight Stat Card
ProPremium, dark-first KPI card with a gradient hairline border, ambient accent glow, gradient icon token and an inline gradient sparkline.
Complexity tier: Primitive Presents a value: held to semantic markup and contrast, with its right-to-left and print gaps recorded and the right-to-left debt allowed only to shrink.
import { SvSpotlightStatCardComponent } from '@styloviz-pro/stat-card';Demo & usage
Basic usage
ProUsage example — open the gallery for the full interactive demo.
An interactive demo for this component lives in the gallery.
Open live demoMore examples
Accent colors
ProSix built-in accent themes drive the border, glow, icon and sparkline gradient.
Downward trend
ProA down trend renders a rose chip with a descending arrow.
When to use
- Premium, dark-themed dashboards where the standard Stat Card looks flat.
- A hero KPI row that needs gradient accents and an inline trend sparkline.
- Marketing / product surfaces where visual polish sells the metric.
Async states
- loading
- error
- retry
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| loading | boolean | false | True while the figure is being fetched. |
| error | SvDataError | string | null | null | The figure could not be loaded. Replaces the number, so the tile never shows a stale one as current. Use `toSvDataError()` from `@styloviz/core` to normalize an `HttpErrorResponse`. |
| title | string | '' | Metric label. |
| value | string | number | '' | Primary value (already formatted, e.g. "1.24M" or "42.3"). |
| prefix | string | '' | Text rendered before the value (e.g. "$"). |
| suffix | string | '' | Text rendered after the value (e.g. "%"). |
| trend | StatCardTrend | 'neutral' | Trend direction — drives the chip color and arrow. |
| trendPercent | number | null | null | Percentage change shown in the trend chip. |
| trendLabel | string | '' | Caption next to the trend chip (e.g. "vs last month") — the comparison period. Also read into the chip's accessible name; where it is missing the name says "comparison period not stated" rather than a bare percentage. |
| updatedAt | string | '' | When this figure was last refreshed, as `YYYY-MM-DD` or an ISO timestamp. Renders an "Updated … ago" line, as on `sv-stat-card-pro`. A cached KPI looks identical to a live one — and this is the card built to be the loudest figure on the page. |
| staleAfterMinutes | number | 60 | How many minutes before the figure is called out as possibly stale. |
| source | string | '' | Where the figure came from — a warehouse, a job, a service. |
| accent | SpotlightAccent | 'violet' | Accent color theme. |
| icon | string | '' | Name of an icon in `@styloviz/icons` (was a raw 24×24 SVG path). |
| sparkline | SparkPoint[] | [] | Sparkline points; rendered as a gradient area behind the value. |
| customClass | string | '' | Extra classes for the root element. |
Outputs
| Event | Payload type | Description |
|---|---|---|
| retry | void | The host should re-run the failed load. |
Wire it to your API
This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.
Template
ProBound to the names this component actually exposes.
Host class
ProDrive the three async inputs from your own fetch.
- This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `sparkline`, `loading` and `error`.
- Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.
Full walkthrough: Connecting to a backend.
Customization & theming
- Six accents: violet, cyan, emerald, amber, rose, blue.
- Gradient border, glow, icon token and sparkline all derive from the accent.
- Pass `sparkline` points to render the inline gradient area; omit it to hide the chart.
- Name any glyph from the icon library with `icon`.
Best practices
- Do: Pre-format the `value` (e.g. `1.24M`, `$847K`) before binding.
- Do: Map each metric to a distinct `accent` so a KPI row reads at a glance.
- Don't: Don't place it on a busy multicolor background — it shines on dark or neutral canvases.
Accessibility
- Value, trend and label are real text, not images.
- The sparkline is decorative and hidden from assistive tech (`aria-hidden`).
- Each instance gets a unique gradient id so multiple cards never collide.
- Trend chip color is reinforced with a directional arrow, not color alone.
Feedback on Spotlight Stat Card
Spotted a gap in this page, or something that didn't work as described? Comments are GitHub Discussions in the public styloviz/community repo, so posting needs a GitHub account.