> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/card.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Card

Group related content and actions in a container.


## Basic usage

Supply the card title through `title` and its content through `children`.


### Project details

Keep project notes and related resources together.

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/basic.tsx"
import { Card } from '@ifhover/leaf-ui';

export function CardBasic() {
  return <Card title="Project details">Keep project notes and related resources together.</Card>;
}
```

Expand code


## Examples

### Selected state

`selected` is visual only. Use a button or selection control to make a card selectable.


### Personal

For individual use.

Select plan

### Team

For team collaboration.

Select plan

selected.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/selected.tsx"
import { Button, Card, Flex } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CardSelected() {
  const [selected, setSelected] = useState('personal');
  return (
    <Flex direction="column" gap={16}>
      {[
        { key: 'personal', title: 'Personal' },
        { key: 'team', title: 'Team' },
      ].map((option) => (
        <Card
          key={option.key}
          title={option.title}
          selected={selected === option.key}
          footer={
            <Button aria-pressed={selected === option.key} onClick={() => setSelected(option.key)}>
              Select plan
            </Button>
          }
        >
          {option.key === 'personal' ? 'For individual use.' : 'For team collaboration.'}
        </Card>
      ))}
    </Flex>
  );
}
```

Expand code

### Sizes

Embedded tabs follow the card's `size` unless overridden with `tabs.size`, and have the same height as standalone line Tabs of that size. Buttons and inputs inside the card use their own `size`.


Small

### Project details

The same card content.

Default

### Project details

The same card content.

Large

### Project details

The same card content.

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/sizes.tsx"
import { Card, Flex, Text } from '@ifhover/leaf-ui';

const sizes = [
  { size: 'sm', label: 'Small' },
  { size: 'md', label: 'Default' },
  { size: 'lg', label: 'Large' },
] as const;

export function CardSizes() {
  return (
    <Flex direction="column" gap="lg">
      {sizes.map(({ size, label }) => (
        <Flex key={size} direction="column" gap="sm">
          <Text tone="muted">{label}</Text>
          <Card title="Project details" size={size}>
            The same card content.
          </Card>
        </Flex>
      ))}
    </Flex>
  );
}
```

Expand code

### Layered card

Set `variant="layered"` to separate the heading from the content card. This appearance does not display `description`.


### Project progress

In progress

Document component usage and add interactive examples.

60%

6 of 10 tasks completedDue Friday

layered.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/layered.tsx"
import { Card, Flex, Progress, Space, Tag, Text } from '@ifhover/leaf-ui';

export function CardLayered() {
  return (
    <Card title="Project progress" extra={<Tag variant="soft">In progress</Tag>} variant="layered">
      <Space direction="vertical" align="stretch" size="md">
        <Text>Document component usage and add interactive examples.</Text>
        <Progress percent={60} aria-label="Project completion" />
        <Flex justify="space-between" gap="sm" wrap>
          <Text tone="muted">6 of 10 tasks completed</Text>
          <Text tone="muted">Due Friday</Text>
        </Flex>
      </Space>
    </Card>
  );
}
```

Expand code

### Standalone title

`CardTitle` can be used outside a card and renders `<h3>` by default. Use `level` to match the document hierarchy without changing its visual size.


### Project details

Keep notes and reference materials together.

standalone-title.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/standalone-title.tsx"
import { CardTitle } from '@ifhover/leaf-ui';

export function CardStandaloneTitle() {
  return (
    <CardTitle description="Keep notes and reference materials together.">
      Project details
    </CardTitle>
  );
}
```

Expand code

### Heading and footer actions

Place actions beside the title with `extra`, or below the content with `footer`.


### Project details

Reset

There are unsaved changes.

Save

actions.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/actions.tsx"
import { Button, Card, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CardActions() {
  const [saved, setSaved] = useState(false);

  return (
    <Card
      title="Project details"
      extra={
        <Button variant="link" disabled={!saved} onClick={() => setSaved(false)}>
          Reset
        </Button>
      }
      footer={
        <Flex justify="end">
          <Button disabled={saved} onClick={() => setSaved(true)}>
            Save
          </Button>
        </Flex>
      }
    >
      <Text role="status">{saved ? 'Changes saved.' : 'There are unsaved changes.'}</Text>
    </Card>
  );
}
```

Expand code

### Tabbed card

Use `tabs.items` for tab pages. Provide `tabs['aria-label']` when the card has no title. Each item's `children` holds its page; omit item `children` when using the tab bar solely to switch state for Card's `children` below.


Overview

Activity

Keep design and development working from the same plan.

tabs.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/tabs.tsx"
import { Card, Text } from '@ifhover/leaf-ui';

export function CardTabs() {
  return (
    <Card
      tabs={{
        'aria-label': 'Project overview',
        items: [
          {
            key: 'overview',
            label: 'Overview',
            children: <Text>Keep design and development working from the same plan.</Text>,
          },
          {
            key: 'activity',
            label: 'Activity',
            children: <Text>The component guidelines were updated today.</Text>,
          },
        ],
      }}
    />
  );
}
```

Expand code

### Heading with tabs

Control the active tab with `tabs.activeKey`
 and `tabs.onChange`
. Visited pages retain input state by default; use `destroyInactive`
 to unmount them when leaving. See the [Tabs API
](tabs.html#tabs-api) (opens in a new tab) for other tab interactions.

### Project settings

Details

Notes

Project name

Not savedSave changes

tabs-with-title.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/tabs-with-title.tsx"
import { Button, Card, Flex, Form, FormField, Input, Text } from '@ifhover/leaf-ui';
import { useId, useState } from 'react';

export function CardTabsWithTitle() {
  const [activeKey, setActiveKey] = useState('settings');
  const [saved, setSaved] = useState(false);
  const formId = useId();
  return (
    <Card
      title="Project settings"
      tabs={{
        activeKey,
        onChange: setActiveKey,
        items: [
          {
            key: 'settings',
            label: 'Details',
            children: (
              <Form
                id={formId}
                layout="vertical"
                onChange={() => setSaved(false)}
                onSubmit={(event) => {
                  event.preventDefault();
                  setSaved(true);
                }}
              >
                <FormField label="Project name">
                  <Input name="name" defaultValue="Leaf Design System" required />
                </FormField>
              </Form>
            ),
          },
          {
            key: 'notes',
            label: 'Notes',
            children: <Text>Save the project name from the Details tab after editing it.</Text>,
          },
        ],
      }}
      footer={
        <Flex align="center" gap="sm" justify="space-between" wrap>
          <Text role="status" tone="muted">
            {saved ? 'Saved' : 'Not saved'}
          </Text>
          <Button type="submit" form={formId} disabled={activeKey !== 'settings'}>
            Save changes
          </Button>
        </Flex>
      }
    />
  );
}
```

Expand code

### Loading state

`loading` replaces the body and tab pages with skeletons. It does not disable headings, tabs or actions; the application must disable any actions that should be unavailable.


Loading

### Project details

loading.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/card/loading.tsx"
import { Card, Flex, Switch } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CardLoading() {
  const [loading, setLoading] = useState(true);

  return (
    <Flex direction="column" gap="md">
      <Switch checked={loading} onChange={(event) => setLoading(event.currentTarget.checked)}>
        Loading
      </Switch>
      <Card title="Project details" loading={loading}>
        Keep project notes and related resources together.
      </Card>
    </Flex>
  );
}
```

Expand code


## API

### Card API

Configuration for card headings, content regions, embedded tabs and loading state.

| Property      | Type                             | Default     | Description                                                                                           |
| ------------- | -------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `title`       | `ReactNode`                      | —           | Card heading.                                                                                         |
| `description` | `ReactNode`                      | —           | Supporting text below the title; only supported by the default appearance, not layered.               |
| `extra`       | `ReactNode`                      | —           | Heading actions; shown at the trailing edge of tabs without a heading.                                |
| `tabs`        | [`CardTabsProps`](#cardtabs-api) | —           | Embedded tabs; replace the heading without a title or sit beneath it.                                 |
| `cover`       | `ReactNode`                      | —           | Top cover.                                                                                            |
| `footer`      | `ReactNode`                      | —           | Footer content or actions; layered places them on the canvas below the content card.                  |
| `loading`     | `boolean`                        | `false`     | Replace body and tab-page content with skeletons; headings, tabs and actions remain enabled.          |
| `bordered`    | `boolean`                        | `true`      | Show the outer border; set to `false` to remove it.                                                   |
| `shadow`      | `boolean`                        | `true`      | Show the card's resting shadow; layered cards apply it to the inner content surface.                  |
| `selected`    | `boolean`                        | `false`     | Mark the card as selected; use a button or selection control to manage selection.                     |
| `variant`     | `'default' \| 'layered'`         | `'default'` | Card appearance; layered separates the content surface from the heading and footer on a muted canvas. |
| `size`        | `'sm' \| 'md' \| 'lg'`           | `'md'`      | Card size; embedded tabs follow it by default, while other children use their own sizes.              |

### CardTabs API

See the [Tabs API
](tabs.html#tabs-api) (opens in a new tab) for embedded tab props. Card fixes `type="line"`
 and `placement="top"`
, adds loading skeletons to tab content, and keeps `tabs.extra`
 on the tab bar; an empty `items`
 list restores an ordinary card.
```ts
type CardTabsProps = Omit<TabsProps, 'type' | 'placement' | 'children'>;
```

### CardTitle API

Supports native heading attributes and a ref to the actual heading element. `ConfigProvider` defaults for `components.CardTitle` affect directly rendered titles only; internal Card headings follow the Card size.

| Property         | Type                                               | Default | Description                                                                                                                 |
| ---------------- | -------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `size`           | `'sm' \| 'md' \| 'lg'`                             | `'md'`  | Visual size, matching the heading in the corresponding Card size.                                                           |
| `description`    | `ReactNode`                                        | —       | Supporting text beneath the heading.                                                                                        |
| `extra`          | `ReactNode`                                        | —       | Trailing heading actions.                                                                                                   |
| `level`          | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                       | `3`     | Optional semantic level; defaults to h3 like Card without changing visual size.                                             |
| `containerProps` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` | —       | Native attributes for the title-region wrapper; heading attributes, events and ref still target the actual heading element. |
| `children`       | `ReactNode`                                        | —       | Heading content.                                                                                                            |
| `ref`            | `Ref<HTMLHeadingElement>`                          | —       | Reference to the heading element.                                                                                           |
