Metric

Server component, no client JS

ImportCopy Anchor Link

import { Metric } from '@nizivo/react/metric';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/delta.css and @nizivo/react/css/inline-error.css and @nizivo/react/css/number-value.css and @nizivo/react/css/skeleton.css
import '@nizivo/react/css/metric.css';

Static or interactiveCopy Anchor Link

Server. It ships no client JavaScript when a Server Component renders it, in every Next.js build mode; its code is bundled only when a client component (a 'use client' file) imports it. A chart in its chart slot ships what its own module ships. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

See Dashboard for the status contract it shares with KpiTile, TrendCard and RankedList.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Delta } from '@nizivo/react/delta';
import { Metric } from '@nizivo/react/metric';

const USD = { style: 'currency', currency: 'USD', maximumFractionDigits: 0 } as const;

export function MetricExample(): JSX.Element {
  return (
    <div>
      <Metric
        label="Total sales"
        value={48290}
        format={USD}
        delta={0.124}
        comparison="vs last week"
      />
      {/* A rise in refunds is bad news: pass your own Delta for the tone */}
      <Metric
        label="Refunds"
        value={1290}
        format={USD}
        delta={<Delta value={0.08} tone="critical" />}
        comparison="vs last month"
      />
      <Metric
        size="display"
        label="Total sales"
        value={123307.4}
        format={{ style: 'currency', currency: 'USD', minimumFractionDigits: 2 }}
        delta={0.182}
      />
    </div>
  );
}

import type { JSX } from 'react';
import { Metric } from '@nizivo/react/metric';

export function MetricStatesExample(): JSX.Element {
  return (
    <div>
      <Metric label="Orders" status="loading" comparison="vs last week" />
      <Metric label="Orders" value={null} comparison="vs last week" />
      <Metric label="Orders" status="error" comparison="vs last week" />
      <Metric label="Orders" value={1284} delta={-0.031} comparison="vs last week" pending />
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

MetricDataProps type

import type { MetricDataProps } from '@nizivo/react/metric'

The value and status props Metric, KpiTile and TrendCard share.

Name	Type	Default	Description
comparison	ReactNode	–	Visible text after the delta, for example "vs last week".
delta	number | ReactElement	–	The change. A number renders <Delta value={delta} locale={locale} /> (a fraction: 0.124 is "+12.4%"); pass your own <Delta … /> element for another format, a tone or an icon.
empty	ReactNode	–	Replaces the "—" of the empty state.
error	ReactNode	–	Replaces the InlineError of the error state, for example one with a Retry action.
format	Intl.NumberFormatOptions	{}	Intl.NumberFormat options for the value.
labelrequired	ReactNode	–	The name of the number, for example "Total sales". Also names the status texts.
labels	Partial<MetricLabels>	–
locale	string	'en-US'	BCP 47 tag for the value and a numeric delta.
pending	boolean	–	A refresh is in flight while the value shows: data-pending and aria-busy.
status	DataStatus "ready" | "loading" | "empty" | "error"	'ready'	§16.5 lifecycle.
value	number | null	–	The number. null or undefined (or NaN) with status="ready" renders the empty state.

MetricLabels type

import type { MetricLabels } from '@nizivo/react/metric'

Strings Metric renders (§16.4), all visually hidden or replaceable by a slot. {label} is replaced by the label prop.

Name	Type	Default	Description
emptyrequired	string	'No data'	Read after the "—" when there is no value and no empty slot.
errorrequired	string	'Could not load {label}'	The InlineError message when loading failed and there is no error slot.
loadingrequired	string	'Loading {label}'	Static text while status="loading" (§16.5: aria-busy plus this, no live region).

MetricProps type

import type { MetricProps } from '@nizivo/react/metric'

The props of Metric, listed above.

MetricSize type

import type { MetricSize } from '@nizivo/react/metric'

default: Numeric/KPI, the change on its own row (KPI Tile). display: Numeric/Display, the change beside the number (Revenue Card).

type MetricSize = "default" | "display"

MetricState type

import type { MetricState } from '@nizivo/react/metric'

The render state of Metric, listed above.

metricLabels constant

import { metricLabels } from '@nizivo/react/metric'

English defaults of Metric's strings; KpiTile and TrendCard use them too.

const metricLabels: MetricLabels

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-inline-error, .nz-inline-error-message, .nz-metric, .nz-metric-change, .nz-metric-change-skeleton, .nz-metric-chart, .nz-metric-comparison, .nz-metric-empty, .nz-metric-label, .nz-metric-value, .nz-metric-value-row, .nz-metric-value-skeleton.

AccessibilityCopy Anchor Link

Nothing in this component takes focus or keyboard input.

KeyboardCopy Anchor Link

None.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: none