# Card and Cards Tag [](/learn/markdoc/tags/tag-library#redocly-tag-badge)

The `card` and `cards` tags work together to create visually appealing, structured content elements ("cards") in your documentation.

The `card` tag allows you to create an individual card element that contains your markup, while the `cards` tag organizes multiple cards into a responsive grid layout.

## Syntax and usage

Add an opening and closing `cards` tag to wrap the card elements.


```markdoc
{% cards %}
{% /cards %}
```

Wrap content in a `card` and configure them using attributes.
A card only works as a child of `cards`.


```markdoc
{% cards %}
  {% card title="First card" icon="images/first-card.svg" %}
    I'm a **card**.
  {% /card %}
  {% card title="Second card" icon="images/second-card.svg" %}
    I'm a card, _too_.
  {% /card %}
  {% card title="Third card" icon="images/third-card.svg" %}
    I'm actually a brochure.
  {% /card %}
{% /cards %}
```

## Attributes - Card

| Attribute | Type | Description |
|  --- | --- | --- |
| `title` | string | **REQUIRED.** The title of the card. |
| `to` | string | URL or path for the card to link to. When set, the entire card behaves as a link. |
| `variant` | string | Visual style of the card. Can be `filled`, `outlined`, `elevated`, or `ghost`. Defaults to `filled`. |
| `image` | string | Path to an image to display in the card. |
| `imagePosition` | string | Set position of the image in the card to `start` or `end`. Defaults to `start`. |
| `icon` | string | Path to an icon to display on the card. Supports image files or SVGs. |
| `iconVariant` | string | Style of the icon. Can be `filled` or `ghost`. |
| `lineClamp` | string | Limits the number of lines of text displayed in the card content.
Once exceeded, text cuts off at the first white space and "..." is appended. |
| `layout` | string | Layout of the card. Can be `horizontal` or `vertical`. Defaults to `vertical`. |
| `align`
 | string
 | Alignment of card content. Can be `start`, `center`, or `end`. Defaults to `start`. Card orientation changes with layout:
- For horizontal layouts, `start` means left.
- For vertical layouts, `start` means top.

 |


## Attributes - Cards

| Attribute | Type | Description |
|  --- | --- | --- |
| `columns` | Number | Set the number of columns in the grid. Defaults to 3. |
| `cardMinWidth` | string | Minimum width of each card in pixels. Cards will shrink to this size before pushing the next card to the following row. Defaults to 240. |


## Examples

### Card variants

Use the `variant` attribute to change the appearance of the card with pre-configured styles.

Filled card
Uses `filled` variant.

Outlined card
Uses `outlined` variant.

Elevated card
Uses `elevated` variant.

Ghost card
Uses `ghost` variant.

details
summary
See card variant example syntax

```
{% cards columns=4 cardMinWidth=180 %}

  {% card title="Filled card" variant="filled" %}
    Uses `filled` variant.
  {% /card %}

  {% card title="Outlined card" variant="outlined" %}
    Uses `outlined` variant.
  {% /card %}

  {% card title="Elevated card" variant="elevated" %}
    Uses `elevated` variant.
  {% /card %}

  {% card title="Ghost card" variant="ghost" %}
    Uses `ghost` variant.
  {% /card %}

{% /cards %}
```

### Cards as links

Set the `to` attribute to configure the entire card as a link.
Each card variant has unique hover styles for cards as links.

Filled card
Hover to see styles.

Outlined card
Hover to see styles.

Elevated card
Hover to see styles.

Ghost card
Hover to see styles.

details
summary
See link cards example syntax

```
{% cards columns=4 cardMinWidth=180 %}

  {% card title="Filled card" to="#cards-as-links" variant="filled" %}
    Hover to see styles.
  {% /card %}

  {% card title="Outlined card" to="#cards-as-links" variant="outlined" %}
    Hover to see styles.
  {% /card %}

  {% card title="Elevated card" to="#cards-as-links" variant="elevated" %}
    Hover to see styles.
  {% /card %}

  {% card title="Ghost card" to="#cards-as-links" variant="ghost" %}
    Hover to see styles.
  {% /card %}

{% /cards %}
```

### Icon cards

Use the `icon` attribute to add an icon to a card and choose its styles with `iconVariant`.

Filled card
...with `filled` icon variant.

Outlined card
...with `ghost` icon variant.

Elevated card
...with `filled` icon variant.

Ghost card
...with `ghost` icon variant.

details
summary
See icon cards example syntax

```
{% cards columns=4 cardMinWidth=180 %}

  {% card title="Filled card" icon="images/ghost-icon.svg" to="#cards-as-links" variant="filled" iconVariant="filled" %}
    ...with `filled` icon variant.
  {% /card %}

  {% card title="Outlined card" icon="images/ghost-icon.svg" to="#cards-as-links" variant="outlined" iconVariant="ghost" %}
    ...with `ghost` icon variant.
  {% /card %}

  {% card title="Elevated card" icon="images/ghost-icon.svg" to="#cards-as-links" variant="elevated" iconVariant="filled" %}
    ...with `filled` icon variant.
  {% /card %}

  {% card title="Ghost card" icon="images/ghost-icon.svg" to="#cards-as-links" variant="ghost" iconVariant="ghost" %}
    ...with `ghost` icon variant.
  {% /card %}

{% /cards %}
```

#### Icon card positioning

Use the `layout` and `align` attributes to control the positioning of elements in your icon card.

**Horizontal layout icon cards:**

Icon card
Layout = `horizontal`

Align = `start`

Icon card
Layout = `horizontal`

Align = `center`

Icon card
Layout = `horizontal`

Align = `end`

details
summary
See horizontal icon card example syntax

```
{% cards cardMinWidth=180 %}

  {% card title="Icon card" layout="horizontal" align="start" icon="./images/cards-markdoc/ghost-icon.svg" variant="outlined" %}
    Layout = `horizontal`

    Align = `start`
  {% /card %}

  {% card title="Icon card" layout="horizontal" align="center" icon="./images/cards-markdoc/ghost-icon.svg" variant="outlined" %}
    Layout = `horizontal`

    Align = `center`
  {% /card %}

  {% card title="Icon card" layout="horizontal" align="end" variant="outlined" icon="./images/cards-markdoc/ghost-icon.svg" %}
    Layout = `horizontal`

    Align = `end`
  {% /card %}

{% /cards %}
```

**Vertical layout icon cards:**

Icon card
Layout = `vertical`

Align = `start`

Icon card
Layout = `vertical`

Align = `center`

Icon card
Layout = `vertical`

Align = `end`

details
summary
See vertical icon card example syntax

```
{% cards cardMinWidth=180 %}

  {% card title="Icon card" layout="vertical" align="start" icon="./images/cards-markdoc/ghost-icon.svg" variant="outlined" %}
    Layout = `vertical`

    Align = `start`
  {% /card %}

  {% card title="Icon card" layout="vertical" align="center" icon="./images/cards-markdoc/ghost-icon.svg" variant="outlined" %}
    Layout = `vertical`

    Align = `center`
  {% /card %}

  {% card title="Icon card" layout="vertical" align="end" variant="outlined" icon="./images/cards-markdoc/ghost-icon.svg" %}
    Layout = `vertical`

    Align = `end`
  {% /card %}

{% /cards %}
```

### Image cards

Add an image to a card using the `image` attribute.

Filled card
...with an image!

Outlined card
...with an image!

Elevated card
...with an image!

Ghost card
...with an image!

details
summary
See image cards example syntax

```
{% cards columns=4 cardMinWidth=180 %}

  {% card title="Filled card" image="images/card-gradient.jpeg" to="#cards-as-links" variant="filled" %}
    ...with an image!
  {% /card %}

  {% card title="Outlined card" image="images/card-gradient.jpeg" to="#cards-as-links" variant="outlined" %}
    ...with an image!
  {% /card %}

  {% card title="Elevated card" image="images/card-gradient.jpeg" to="#cards-as-links" variant="elevated" %}
    ...with an image!
  {% /card %}

  {% card title="Ghost card" image="images/card-gradient.jpeg" to="#cards-as-links" variant="ghost" %}
    ...with an image!
  {% /card %}

{% /cards %}
```

#### Image card positioning

Use the `layout`, `align`, and `imagePosition` attributes to control the positioning of elements in your image card.

**Vertical layout image cards:**

Image card
Layout = `vertical`

Align = `start`

imagePosition = `start`

Image card
Layout = `vertical`

Align = `center`

imagePosition = `start`

Image card
Layout = `vertical`

Align = `end`

imagePosition = `end`

details
summary
See vertical image card example syntax

```
{% cards cardMinWidth=180 %}

  {% card title="Image card" layout="vertical" align="start" imagePosition="start" image="images/card-gradient.jpeg" variant="outlined" %}
        Layout = `vertical`

        Align = `start`

        imagePosition = `start`
  {% /card %}

  {% card title="Image card" layout="vertical" align="center" imagePosition="start" image="images/card-gradient.jpeg" variant="outlined" %}
        Layout = `vertical`

        Align = `center`

        imagePosition = `start`
  {% /card %}

  {% card title="Image card" layout="vertical" align="end" imagePosition="end" image="images/card-gradient.jpeg" variant="outlined" %}
        Layout = `vertical`

        Align = `end`

        imagePosition = `end`
  {% /card %}

{% /cards %}
```

**Horizontal layout image cards:**

Image card
Layout = `horizontal`

Align = `start`

imagePosition = `start`

Image card
Layout = `horizontal`

Align = `center`

imagePosition = `start`

Image card
Layout = `horizontal`

Align = `end`

imagePosition = `end`

## Best practices

**Group related information**

Cards are great for organizing and presenting related pieces of information. Use them to guide users to resources or highlight important features.

**Keep cards concise**

Cards work best when they present information in a concise way. Avoid overcrowding cards with too many elements.

**Visual consistency**

When using multiple cards, strive for consistent design and content structure. This consistency will keep your documentation looking cohesive and professional.

**Consider responsiveness**

Consider how your card grid will look on different screen sizes. Use the `columns` and `cardMinWidth` attributes to create a layout that works well across devices.

## Debug common issues

**Cards won't render**

Check that you've correctly nested the `card` tags inside a parent `cards` tag.

**Images or icons not showing**

Verify that the filepaths are correct and the file exists at that location.
Incorrect paths will show Markdoc errors in your console.

**Inconsistent card sizes**

Using different amounts of content in each card can make the cards in your grid appear to be different sizes.
Consider rephrasing your content or using the `lineClamp` attribute to maintain a consistent height.