Card

A surface with optional header, title, description, action, body and footer parts. The inverse tone flips every token inside it; brand and accent are the tinted surfaces of the dashboard widgets (KpiTile's tone), with no stroke.

Server component, no client JS

Import

import { Card } from '@nizivo/react/card';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/card.css';

Static or interactive

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. Every part is server-safe; a child you put in Card.Action ships whatever its own component 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.

Tones

tone="brand" and tone="accent" are new in 0.2.0; 0.1.0 has surface, subtle and inverse only. In dark mode bg/brand-subtle and bg/accent-subtle are both green-950, so the two tints look the same there. That is Figma's design, and the code follows it for now (Figma 04 issue 5; the maintainer's decision M42).

On brand and accent, a Delta inside the Card is drawn as a bg/surface pill, so it shows on the tint: Figma's bg/success-subtle pill is the same colour as bg/brand-subtle (green-50 in light, and all three are green-950 in dark), so it would show no fill. This is a deviation from Figma 04 (gap 4) that the maintainer chose (M42). The pill's text keeps its colour, at least 5.68:1 on bg/surface in light and 5.96:1 in dark (text/critical; CONTRAST.md). The nearest Card decides: a Delta inside an untinted Card nested in a tinted one keeps its own pill. A --nz-delta-bg you set still wins.

The surface variable

Card declares --nz-surface, the colour it paints, in every tone (and so do KpiTile and TrendCard, which are Cards). Any child can read it to match the surface it sits on, for example a ring or a gap that should look cut out of the card:

.my-marker {
  box-shadow: 0 0 0 2px var(--nz-surface, var(--nz-bg-surface));
}

It is read-only: Card sets it; set --nz-card-bg to change the surface, and --nz-surface follows.
It is not a token. Outside a Card it is undefined, so always read it with a fallback.
Inside tone="inverse" it resolves in the inverse colour scheme, as every token there does.
@nizivo/charts reads it with a fallback: a Sparkline's end-dot halo, for example, takes the tinted tile's colour instead of a white ring, and still works on a page without @nizivo/react.

Examples

Basic

Top products

Last 30 days

Stoneware mug In stock

Plan

Grow, billed monthly

Share your store to get your first order.

import type { JSX } from 'react';
import { Badge } from '@nizivo/react/badge';
import { Button } from '@nizivo/react/button';
import { Card } from '@nizivo/react/card';

export function CardExample(): JSX.Element {
  return (
    <div>
      <Card.Root>
        <Card.Header>
          <Card.Title>Top products</Card.Title>
          <Card.Description>Last 30 days</Card.Description>
          <Card.Action>
            <Button variant="tertiary" size="sm">
              View all
            </Button>
          </Card.Action>
        </Card.Header>
        <Card.Body>
          Stoneware mug <Badge tone="success">In stock</Badge>
        </Card.Body>
        <Card.Footer>
          <Button size="sm">Export</Button>
        </Card.Footer>
      </Card.Root>
      <Card.Root tone="subtle">
        <Card.Title level={2}>Plan</Card.Title>
        <Card.Body>Grow, billed monthly</Card.Body>
      </Card.Root>
      <Card.Root tone="inverse" render={<section aria-label="Tip" />}>
        <Card.Body>Share your store to get your first order.</Card.Body>
      </Card.Root>
    </div>
  );
}

Tones

The tinted surfaces (M41): a row of related widgets shares one tint; it never encodes data.

Holiday drop is ready

Brand: bg/brand-subtle, no stroke.

Restock soon

Accent: bg/accent-subtle, no stroke.

import type { JSX } from 'react';
import { Card } from '@nizivo/react/card';

export function CardTonesExample(): JSX.Element {
  return (
    <div>
      <Card.Root tone="brand">
        <Card.Title>Holiday drop is ready</Card.Title>
        <Card.Body>Brand: bg/brand-subtle, no stroke.</Card.Body>
      </Card.Root>
      <Card.Root tone="accent">
        <Card.Title>Restock soon</Card.Title>
        <Card.Body>Accent: bg/accent-subtle, no stroke.</Card.Body>
      </Card.Root>
    </div>
  );
}

Parts

Use the parts through the namespace (Card.Root) or by their flat names (CardRoot); both work from Server Components.

Card.Root

Server component Renders data-slot="card" with the class nz-card. Props: CardRootProps. Source: src/card/card.tsx.

Name	Type	Default	Description
`elevation`	`CardElevation` `01`	`0`	No shadow at rest until design says otherwise (decision 8j).
`padding`	`CardPadding` `"sm""md"`	`'md'`
`render`	`RenderProp<CardRootState>`	–
`tone`	`CardTone` `"surface""subtle""inverse""brand""accent"`	`'surface'`	`inverse` sets `data-nz-scheme="inverse"`, so every token inside resolves in the inverse scheme. Every tone declares `--nz-surface`, the colour the card paints, for children to read with a fallback (`var(--nz-surface, var(--nz-bg-surface))`); on `brand` and `accent` a Delta pill inside is `bg/surface`, so it shows on the tint (M42).

Also takes every attribute of <div>. (ComponentPropsWithRef<"div">)

render takes an element, or, in client code, a function of the props and this state (CardRootState):

Name	Type	Default
`elevation`required	`CardElevation` `01`	–
`padding`required	`CardPadding` `"sm""md"`	–
`tone`required	`CardTone` `"surface""subtle""inverse""brand""accent"`	–

Card.Header

Server component Renders data-slot="card-header" with the class nz-card-header. Props: CardHeaderProps. Source: src/card/card.tsx.

Name	Type	Default	Description
`render`	`RenderProp<Record<string, never>>`	–

Also takes every attribute of <div>. (ComponentPropsWithRef<"div">)