# Cards

> Link to other pages with cards that carry an icon, a title, and a short description. Arrange them in a grid with card groups.

Cards are bordered blocks with an icon, a title, and a short description. Give one an `href` and the whole card becomes a link, which makes cards a good fit for "where to next" sections and landing pages.

<Card title="Quickstart" icon="rocket-launch" href="https://docs.typemark.dev/quickstart">
  Go from sign-up to a live docs site in a few minutes.
</Card>

```mdx
<Card title="Quickstart" icon="rocket-launch" href="/quickstart">
  Go from sign-up to a live docs site in a few minutes.
</Card>
```

## Card groups

Wrap cards in `<CardGroup>` to lay them out in a grid. Set `cols` to choose the number of columns. On phones, every group collapses to one column.

<CardGroup cols={3}>
  <Card title="Callouts" icon="megaphone" href="https://docs.typemark.dev/components/callouts">
    Info, warning, danger, and tip blocks.
  </Card>
  <Card title="Tabs" icon="rectangle-group" href="https://docs.typemark.dev/components/tabs">
    Alternatives side by side.
  </Card>
  <Card title="Steps" icon="list-bullet" href="https://docs.typemark.dev/components/steps">
    Numbered instructions.
  </Card>
</CardGroup>

```mdx
<CardGroup cols={3}>
  <Card title="Callouts" icon="megaphone" href="/components/callouts">
    Info, warning, danger, and tip blocks.
  </Card>
  <Card title="Tabs" icon="rectangle-group" href="/components/tabs">
    Alternatives side by side.
  </Card>
  <Card title="Steps" icon="list-bullet" href="/components/steps">
    Numbered instructions.
  </Card>
</CardGroup>
```

## Links

- An `href` starting with `/` links to a page on your site, like `/quickstart`. The card shows an arrow.
- An `href` starting with `http://` or `https://` opens in a new tab, and the card shows an external-link icon.
- Without `href`, the card is a plain block.

<CardGroup cols={2}>
  <Card title="Key concepts" icon="light-bulb" href="https://docs.typemark.dev/key-concepts">
    Projects, pages, and `typemark.json`.
  </Card>
  <Card title="Heroicons" icon="swatch" href="https://heroicons.com">
    Browse every icon name you can use.
  </Card>
</CardGroup>

```mdx
<CardGroup cols={2}>
  <Card title="Key concepts" icon="light-bulb" href="/key-concepts">
    Projects, pages, and `typemark.json`.
  </Card>
  <Card title="Heroicons" icon="swatch" href="https://heroicons.com">
    Browse every icon name you can use.
  </Card>
</CardGroup>
```

## Icons

The `icon` prop takes any of these:

| Value | Example |
|-------|---------|
| A [Heroicons](https://heroicons.com/) outline name | `bolt`, `code-bracket`, `cog-6-tooth` |
| A common alternative name Typemark maps to a Heroicon | `rocket`, `gear`, `book`, `terminal`, `code` |
| An image path or URL | `/images/logomark.svg` |
| An emoji | `📦` |

An icon name Typemark doesn't know shows no icon, rather than the name as text.

## Images

Set `img` to show an image across the top of the card.

<Card title="Brand assets" img="https://docs.typemark.dev/assets/images/logo.svg">
  A card with an image across the top.
</Card>

```mdx
<Card title="Brand assets" img="/images/logo.svg">
  A card with an image across the top.
</Card>
```

## Props

### Card

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | string | none | The card's heading. |
| `icon` | string | none | Heroicons name, image path or URL, or emoji. |
| `href` | string | none | Makes the whole card a link. External URLs open in a new tab. |
| `img` | string | none | Image path or URL shown across the top of the card. |

The text between the tags is the card's description.

### CardGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `cols` | number | `2` | Number of columns, from 1 to 4. |

## Also accepted

`<Columns>` works the same as `<CardGroup>` and takes the same `cols` prop. The visual editor shows it as a card group and saves it back as `<Columns>`.

## In the visual editor

Type `/` and pick **Card** or **Card group**. Each card has an icon picker, a title field, and a link field. In a card group, choose 1, 2, or 3 columns from the dropdown, click **Add card** to add one, and hover a card to remove it.

<Callout type="tip">
  Keep card descriptions to a sentence. Cards are for scanning; the page they link to does the explaining.
</Callout>
