# Metric Card Show a key figure with its change and context. Views in 24 hours with a framed chart **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-demo ``` This Pattern is part of [Siteplane UI Pro](/pricing), and its source comes with a [Pro license](/docs/license/#patterns). Its previews are free to view and try. ## Installation **Pro** — Installs with a Siteplane UI Pro license key. Complete the one-time [Pro setup](/docs/installation/#siteplane-ui-pro) first. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card ``` With npm: `npx shadcn@4.18.0 add @siteplane-pro/metric-card`. ## Usage ```tsx import { MetricCard } from "@/siteplane/components/metric-card"; ; ``` ## Simple figure The default layout shows the title, the figure and its change in a badge. Pass `menuItems` for a three-dot menu in the corner and `actions` for a footer below a divider. A link button with `ms-auto` moves a single destination to the end of the footer. In a narrow card the badge moves under the figure, and a chart stays beside them, so the figure never runs under the badge. The width at which this happens follows from the parts the card shows, such as a comparison or a chart, and stays the same however long their text is. Page views and unique visitors **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-simple-example ``` ## Icon above the title Pass an `icon` to show it above the title. The icon is bare, without a frame, and decorative. `icon-top` tints it with the success color and keeps the change in a badge. `icon-top-inline` keeps the icon in the text color and sets the change and its `comparison` at the end of the figure’s row. Icon layouts above the title **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-icon-top-example ``` ## Icon beside the title `icon-heading` puts the icon in the accent color in front of the title and moves the change below the figure. `icon-leading` gives the icon a column of its own before the title and the figure and keeps the change in a badge. Set `iconTone="neutral"` to draw the icon in the secondary text color, `--sp-rw-fg-secondary`, in every layout: in place of the accent of `icon-heading` and `figure-inline`, the success color of `icon-top` and the text color of the other layouts. A neutral icon suits a module icon and leaves color to states, such as the trend of the change. Icon layouts beside the title **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-icon-side-example ``` ## Chart beside the figure Pass `series` to draw a chart, one array of numbers per series. `chart-aside` sets a small chart at the end of the card with the change below the figure. `chart-overlay` layers several series as soft overlapping areas and takes an `icon` in front of the title. Small charts beside the figure **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-chart-side-example ``` ## Full-width chart `chart-full` draws the chart across the card below the figure. `chart-frame` moves the title into a header above a divider and draws the chart across the panel. Charts across the card **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-chart-full-example ``` ## Figures without a card The `figure` layouts show the figure without its card, for figures inside a card or a panel. `figure` sets the title as a label above the value and the change in a badge after the value, which moves below it when the figure has no room beside it. `figure-large` sets the value at the size of the card layouts, for the first and larger figure of a row, and `figure` is one step smaller. A `comparison` is a quieter line under the figure. `figure-inline` is a small figure for a compact row: an optional icon in the accent color, the title on one line and the value after it. Each figure is a description list of its own, so several sit side by side in a row that you lay out, such as `flex flex-wrap`. The figure layouts take no menu, actions or chart. Place the figures inside the card they describe rather than as a strip of cards above a list. Visitors and page views in an analytics card, with calls, emails and directions in its footer **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-figures-example ``` ## Long titles A long title wraps by default. Set `titleLines` to cut it after that many lines with an ellipsis instead, so cards side by side keep one height; hovering a cut title shows it in full in a tooltip. The title stays the card's heading with its whole text, so assistive technology reads all of it. `titleLines` uses [Truncate](/docs/components/truncate/), which the Pattern installs. Visitors and returning customers with titles cut after one line **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-title-lines-example ``` ## Falling trend Set `trend="down"` for a decrease. The arrow turns downward and the change and the chart take the destructive color. The card does not decide whether a change is good; it shows the direction you pass. Renewals and weekly active users falling **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-trend-example ``` ## Changing data When new data arrives, the card moves to it. A `value` or `change` with digits rolls to its new value, written as you pass it; the `comparison`, other content and a turned `trend` fade through; the chart morphs into the new series. The card keeps its height, because the change lays out by the width of its area, whatever the length of its text. Booking figures that follow the selected period **Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing). ```bash pnpm dlx shadcn@4.18.0 add @siteplane-pro/metric-card-changing-example ``` ## API reference | Prop | Type | Default | Description | | --- | --- | --- | --- | | MetricCard.title | string | required | Name of the measure in the label weight, --sp-rw-font-weight-label (500): an h3 in the card layouts and the term of a description list in the figure layouts. | | MetricCard.titleLines | number | unset | Cuts the title after this many lines with an ellipsis and shows the full title in a tooltip while it is cut, through Truncate. Unset, the title wraps, and figure-inline keeps it on one line with its full text in a title attribute. | | MetricCard.value | ReactNode | required | The key figure, formatted by the application, in the strong weight, --sp-rw-font-weight-strong (600). A figure wider than its column wraps there. | | MetricCard.change | string | unset | The change, such as 12%. The arrow and the color come from trend. Without it, or empty, the card shows no change. | | MetricCard.comparison | string | unset | Context for the change, such as vs. last month. In the figure layouts it is a quieter line under the figure; figure-inline leaves it out. | | MetricCard.trend | up \| down | up | Direction of the change. up shows a rising arrow in the success color, down a falling arrow in the destructive color; the chart follows. | | MetricCard.variant | MetricCardVariant | simple | Layout of the card: simple, icon-top, icon-heading, icon-top-inline, icon-leading, chart-aside, chart-overlay, chart-full or chart-frame. Without a card: figure, figure-large or figure-inline. | | MetricCard.icon | ReactNode | unset | Bare icon for the icon layouts, chart-overlay and figure-inline. It is hidden from assistive technology. icon-top tints it with the success color, and icon-heading and figure-inline with the accent color. | | MetricCard.iconTone | accent \| neutral | accent | Color of the icon. accent keeps each layout's own color; neutral draws the icon in the secondary text color, --sp-rw-fg-secondary, in every layout. | | MetricCard.series | number[][] | [] | Values of one or more chart series for the chart layouts. They share one scale from the lowest value to the highest, so a small change still shows its shape; the figure tells the size. Until a series has a number, such as while the card loads, the card keeps no room for its chart. | | MetricCard.chartLabel | string | title | Accessible name of the chart. | | MetricCard.actions | ReactNode | unset | Footer content below a divider, spread across the card with space between. Card layouts only. | | MetricCard.menuItems | { label: string; icon?: ReactNode; onClick?: () => void; href?: string }[] | unset | Shows a three-dot menu in the top corner, in a column of its own that the title and the figure keep clear. Pass an svg element as icon to lead the item in the menu's icon style. An item with href renders a link. Card layouts only. | | MetricCard.menuLabel | string | Open menu | Accessible name of the menu button and the menu. | | MetricCard.className | string | unset | Classes for the root element. | MetricCardProps and MetricCardVariant export these contracts. The card is built from Card, Badge, Button, Menu, Separator, Sparkline, Motion and Truncate, and fills the width of its container; a figure without a card is as wide as its content, up to the width of its container. It takes no native div props or ref beyond `className`. Formatting the figure, calculating the change and loading data stay with the application. ## Usage notes Name the measure in `title` and the period in `comparison`; a change without its period is ambiguous. The arrow is hidden from assistive technology and the change is plain text, so state a fall in `change`, for example `-3.1%`, and let an unsigned value mean a rise. The chart is a sparkline without axes, labels or hover values. Show exact numbers in the figure and the change, and describe the shape in `chartLabel`, for example “Views per two hours, rising”. A series of one point, or a change in the number of series, shows at once instead of morphing. With reduced motion, from the system setting or `SiteplaneMotionProvider preset="reduced"`, all new data shows at once. In a narrow card, comparison text much longer than “vs. last quarter” can still wrap and add a line, and a long figure with a comparison can crowd the change. The menu button keeps a column of its own: the title keeps its room, and so does the figure in the `chart-frame` layout, where the change moves under the value before it would reach the button. A figure wider than its column wraps between its characters, and a long title wraps, so neither runs under the button or past the card; `titleLines` cuts the title instead. When several cards share a page, give each menu its own `menuLabel` so assistive technology can tell the menu buttons apart. Place the cards in a grid to build a row of metrics, and keep their loading, empty and error states in the application. Figures that belong to one card or panel go inside it in the figure layouts.