Card

Wrap content in a surface. Make it clickable. Show selection state.

import { Card, CardContent } from '@dashforge/tw';

<Card>
  <CardContent>
    <h3>Card title</h3>
    <p>Card body.</p>
  </CardContent>
</Card>

Quick Start

<Card variant="outlined">
  <CardContent>Outlined surface.</CardContent>
</Card>

<Card variant="elevated">
  <CardContent>Elevated surface (shadow).</CardContent>
</Card>

<Card variant="plain">
  <CardContent>Plain surface (no border, no shadow).</CardContent>
</Card>

Examples

Variants

import { Card, CardContent, Stack } from '@dashforge/tw';

<Stack direction="row" gap={3} wrap>
  <Card variant="outlined">
    <CardContent>Outlined — border, no shadow.</CardContent>
  </Card>
  <Card variant="elevated">
    <CardContent>Elevated — shadow, no border.</CardContent>
  </Card>
  <Card variant="plain">
    <CardContent>Plain — no border, no shadow.</CardContent>
  </Card>
</Stack>

Composition with CardContent

<CardContent> is a padded inner Box (p=4 default). Compose freely:

import { Card, CardContent, Button, Stack } from '@dashforge/tw';

<Card>
  <CardContent>
    <Stack gap={2}>
      <div>
        <div style={{ fontSize: 12, opacity: 0.6 }}>CUSTOMER</div>
        <div style={{ fontSize: 18, fontWeight: 600 }}>ACME Inc.</div>
        <div style={{ fontSize: 13, opacity: 0.7 }}>Enterprise plan</div>
      </div>
      <Stack direction="row" gap={2}>
        <Button size="sm" variant="solid">View</Button>
        <Button size="sm" variant="outline">Archive</Button>
      </Stack>
    </Stack>
  </CardContent>
</Card>

CardActionArea (clickable card)

Wrap interactive content in <CardActionArea> to make the whole card a single clickable surface — with focus ring, hover state, and full keyboard support.

<Card>
  <CardActionArea onClick={() => navigate('/customer/123')}>
    <CardContent>
      <h3>ACME Inc.</h3>
      <p>Tap to view details.</p>
    </CardContent>
  </CardActionArea>
</Card>

<CardActionArea> uses Radix Slot — pass asChild to render onto another element (e.g. a router Link):

<Card>
  <CardActionArea asChild>
    <Link to="/customer/123">
      <CardContent>
        <h3>ACME Inc.</h3>
      </CardContent>
    </Link>
  </CardActionArea>
</Card>

Selected state (filter cards)

Pass selected to toggle aria-pressed — useful for filter-card UX.

import { useState } from 'react';
import { Card, CardActionArea, CardContent, Stack } from '@dashforge/tw';

function PlanPicker() {
  const [selected, setSelected] = useState('pro');
  return (
    <Stack direction="row" gap={3}>
      {['starter', 'pro', 'enterprise'].map((plan) => (
        <Card key={plan}>
          <CardActionArea selected={selected === plan} onClick={() => setSelected(plan)}>
            <CardContent>{plan}</CardContent>
          </CardActionArea>
        </Card>
      ))}
    </Stack>
  );
}

Customizing Box props

<Card> is a thin opinionated <Box> alias — all Box props pass through. Override p, rounded, elevation, etc. directly on Card:

<Card p="lg" rounded="xl" elevation={3}>
  <CardContent p="md">Heavily padded card with bigger radius + shadow.</CardContent>
</Card>

Role-based card (RBAC retrofit)

<Box> got access + visibleWhen in Sprint 4.4 — <Card> inherits both transparently. Use cases: admin-only revenue cards, role-gated dashboard tiles.

<Card access={{ requires: 'finance.view', when: 'denied:hide' }}>
  <CardContent>
    <h3>Monthly revenue</h3>
    <p className="text-3xl font-bold">€48,250</p>
  </CardContent>
</Card>

Engine-reactive visibility

<Card visibleWhen={(engine) => engine.getValue('user.role') === 'admin'}>
  <CardContent>Admin-only tile.</CardContent>
</Card>

Theme defaults

Configure <Card> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Card: {
      defaults: { variant: 'outlined', rounded: 'lg', elevation: 1 },
    },
  },
});

Configurable axes (CardVariantProps):

Non-visual axes (Box access, visibleWhen, event handlers) are per-instance — not theme-configurable.

Note: theme.components.Box.defaults does not cascade into Card — they have independent theme entries. Setting theme.components.Card.defaults.variant = 'elevated' doesn't affect <Box>.

Precedence chain (lowest → highest):

1. Card's built-in defaults (variant: 'outlined', rounded: 'lg', elevation: 1, p: 0).
2. theme.components.Card.defaults (application-wide).
3. Instance prop (<Card variant="elevated" elevation={3} />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.Card.defaults autocompletes to the four axes above.

Reactivity: useComponentDefaults('Card') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

<Card> props

<Card> is a thin alias of <Box> — all Box props apply (p, m, bg, rounded, elevation, access, visibleWhen, ...). The card-specific defaults:

The variant prop is narrowed to 'outlined' \| 'elevated' \| 'plain' (a subset of the full Box variant set).

<CardContent> props

Padded inner Box wrapper. Default p='md'. All Box props apply.

<CardActionArea> props

Slot-polymorphic clickable wrapper.

Slots & slotProps

<Card> doesn't expose a slotProps prop — it uses the compound sub-component pattern instead: you compose <Card> + <CardContent> + <CardActionArea> in JSX, styling each with its own sx / className prop.

This "explicit sub-component" pattern beats slotProps for Card because most consumers compose their own inner content anyway — the anatomy is fluid, not fixed. For fixed-anatomy compound components, see <DataGrid> or <Autocomplete>.

Notes

• Card is a Box alias, not a wrapper. All Box props/behaviors work natively. The "Card" name is just an opinionated default surface — same elevation/border/radius you want 90% of the time.
• Three sub-components, one is enough. <Card> alone (with raw children) works fine for one-off layouts. <CardContent> is for the standard padded interior. <CardActionArea> is only when the whole card is interactive.
• access + visibleWhen come from Box (Sprint 4.4 retrofit). Same contract as the rest of the catalog.
• Cross-flavor portable: the MUI side's @dashforge/ui wraps @mui/material/Card directly. Same compositional pattern.