---
title: Card
description: Use cards to highlight links, actions, or related docs with optional icons, covers, and buttons.
---

Use `Card` when a link needs more context than inline text. Cards can be plain and text-focused, or they can include a generated cover for a more visual entry point.

<ComponentPreview>
  ```mdx
  <Card
    title="Quickstart"
    href="/getting-started/quickstart"
    icon="lucide:rocket"
    cover={{
      icon: "lucide:sparkles",
      glass: true,
      colors: ["#fb7185", "#fb923c"],
      patternSeed:"d"
    }}
  >
    Build and publish your first docs site.
  </Card>
  ```
</ComponentPreview>

## Basic usage

The `title` prop is required. Add an `href` when the card should link somewhere, and use the card body for the optional description.

<ComponentPreview>
  ```mdx
  <Card title="API reference" href="/configure-with-docs-json/api-reference">
    Configure your API reference pages, navigation, and schemas.
  </Card>
  ```
</ComponentPreview>

The description supports Markdown, so you can include emphasis, inline code, and links.

<ComponentPreview>
  ```mdx
  <Card title="Content model" href="/getting-started/content-model">
    Learn how `docs.json`, MDX pages, and reusable components work together.
  </Card>
  ```
</ComponentPreview>

## Add an icon

Use `icon` for a small icon next to the title and description. This is useful for compact cards that should still have a clear visual anchor.

<ComponentPreview>
  ```mdx
  <Card
    title="Format text"
    href="/edit-markdown/format-text"
    icon="lucide:type"
  >
    Use Markdown syntax for headings, lists, links, and emphasis.
  </Card>
  ```
</ComponentPreview>

## Add a cover

Use `cover` when the card should have a visual header. A cover is shown when either `cover.icon` or `cover.text` is set.

### Add cover content

<ComponentPreview>
  ```mdx
  <Card
    title="Model routing"
    href="/edit-markdown/components/tabs"
    cover={{
      icon: "lucide:network",
      text: "Routing",
    }}
  >
    Create a more visual card for important guides or landing pages.
  </Card>
  ```
</ComponentPreview>

### Add glass

Add `glass: true` to place the cover icon and text in a subtle glass-like surface.

<ComponentPreview>
  ```mdx
  <Card
    title="Launch checklist"
    href="/getting-started/quickstart"
    cover={{
      icon: "lucide:circle-check",
      text: "Ready",
      glass: true,
    }}
  >
    Give featured cards a softer, more dimensional cover treatment.
  </Card>
  ```
</ComponentPreview>

### Customize cover colors

`cover.colors` accepts one to four hex colors. If you provide fewer than four colors, the remaining colors are generated automatically.

<ComponentPreview>
  ```mdx
  <Card
    title="Brand guidelines"
    href="/configure-with-docs-json/branding"
    cover={{
      text: "Colors",
      colors: ["#fb6f61", "#f6b44b", "#38c7b5"],
    }}
  >
    Start with your brand colors and let the card generate the rest.
  </Card>
  ```
</ComponentPreview>

Use `colorSeed` to change the generated palette when fewer than four colors are provided.

<ComponentPreview>
  ```mdx
  <Card
    title="Brand guidelines"
    href="/configure-with-docs-json/branding"
    cover={{
      text: "Colors",
      colors: ["#fb6f61", "#f6b44b", "#38c7b5"],
      colorSeed: "123",
    }}
  >
    Keep the same brand color while tuning the generated palette.
  </Card>
  ```
</ComponentPreview>

### Change the cover pattern

Use `patternSeed` when the title-generated pattern does not have the composition you want. This changes the cover pattern without changing the card title or colors.

<Callout type="info" title="Patterns use the card title">
  By default, the cover pattern is generated from the card title. This creates subtle visual variation between cards without requiring you to choose a unique pattern by hand.
</Callout>

<ComponentPreview>
  ```mdx
  <Card
    title="Brand guidelines"
    href="/configure-with-docs-json/branding"
    cover={{
      text: "Pattern",
      colors: ["#fb6f61", "#f6b44b", "#38c7b5"],
      patternSeed: "abc",
    }}
  >
    Keep the same title and colors while tuning the cover composition.
  </Card>
  ```
</ComponentPreview>

<Callout type="tip" title="Use seeds for controlled variation">
  Seed values are arbitrary strings. Change `patternSeed` when you like the colors but want a different composition. Change `colorSeed` when the card is generating some of its colors and you want a different palette.
</Callout>

## Add a button

Use `button` when the card should include a separate call to action. When `button` is set, the button uses `button.href`, and the title still uses `href` if one is provided.

<ComponentPreview>
  ```mdx
  <Card
    title="API reference"
    button={{
      text: "Open reference",
      href: "/configure-with-docs-json/api-reference",
    }}
  >
    Review every available API reference configuration option.
  </Card>
  ```
</ComponentPreview>

You can customize the button color for a single card with light and dark mode variation.

<ComponentPreview>
  ```mdx
  <Card
    title="Branding"
    button={{
      text: "Open branding",
      href: "/configure-with-docs-json/branding",
      color: {
        light: "#059669",
        dark: "#FF692E",
      },
    }}
  >
    Adjust colors, logos, and other visual settings.
  </Card>
  <Card
    title="Branding"
    button={{
      text: "Open branding",
      href: "/configure-with-docs-json/branding",
      color: "#2E90FA",
    }}
  >
    Adjust colors, logos, and other visual settings.
  </Card>
  ```
</ComponentPreview>

## Site-wide defaults

Set card defaults in `docs.json` when you want the same cover palette or button color across the site. Card-level props take precedence over these defaults.

```json
{
  "theme": {
    "card": {
      "cover": {
        "colors": ["#fb7185", "#fb923c"],
        "colorSeed": "abc"
      },
      "button": {
        "color": {
          "light": "#171717",
          "dark": "#f5f5f5"
        }
      }
    }
  }
}
```

Cover colors are resolved in this order: `cover.colors`, `theme.card.cover.colors`, `theme.themeColor`, then the built-in palette. `colorSeed` only changes generated colors, so it has no effect when all four cover colors are set explicitly.

Button colors are resolved in this order: `button.color`, `theme.card.button.color`, `navbar.primary.color`, then the default neutral button style.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `title` | `string` | Required. The card title. |
| `href` | `string` | Optional link target. If no `button` is set, the whole card becomes a link. Uses the same internal, external, and OpenAPI endpoint link rules as MDX links. |
| `icon` | `string` | Optional icon shown next to the title and description. |
| `cover` | `object` | Optional visual cover configuration. The cover appears when `cover.icon` or `cover.text` is set. |
| `button` | `object` | Optional call-to-action button configuration. |
| children | `Markdown` | Optional description content shown below the title. |

### Cover props

| Prop | Type | Description |
| --- | --- | --- |
| `icon` | `string` | Icon shown in the center of the cover. |
| `text` | `string` | Text shown in the center of the cover. |
| `glass` | `boolean` | Adds a subtle glass surface around the cover icon and text. |
| `colors` | `string[]` | One to four hex colors used for the cover. Missing colors are generated automatically. |
| `patternSeed` | `string` | Changes the generated cover pattern without changing the title. |
| `colorSeed` | `string` | Changes generated colors when fewer than four cover colors are provided. |

### Button props

| Prop | Type | Description |
| --- | --- | --- |
| `text` | `string` | Required when `button` is set. The button label. |
| `href` | `string` | Required when `button` is set. The button link target. Uses the same link rules as card `href`. |
| `color` | `string` or<br />`{ light?: string; dark?: string }` | Optional button color. Use a hex string for one color, or separate light and dark colors. |