# Card Group

Use the card-group shortcode to display a group of cards.

## Overview

Added in v0.18.6

Use the `card-group` shortcode to display a group of cards. Add inner `<card>` elements for each [card](card). As an example, the following shortcode displays a group of three cards. See the [card component](card) for additional styling options.

```markdown
{{< card-group padding="3" gutter="3" >}}
    {{< card title="Bootstrap framework" icon="fab bootstrap" >}}
        Build fast, responsive sites with Bootstrap 5. Easily customize your site with the
        source Sass files.
    {{< /card >}}
    {{< card title="Full text search" icon="fas magnifying-glass" >}}
        Search your site with FlexSearch, a full-text search library with zero dependencies.
    {{< /card >}}
    {{< card title="Development tools" icon="fas code" >}}
        Use Node Package Manager to automate the build process and to keep track of
        dependencies.
    {{< /card >}}
{{< /card-group >}}
```

## Aligned rows

Set `align-rows` to `true` to line up the parts of the cards in each visual row. Every card is split into six bands: the image or icon, the title, the subtitle, the highlight, the body, and the footer. Each band is as tall as its tallest entry in the row, so a long subtitle in one card pushes the highlights of its neighbours down to the same line. A card that lacks a part keeps an empty band, so its other parts stay on their neighbours' lines.

Alignment applies to stacked groups only, which is the default `orientation`. It has no effect for any other orientation, or when `scroll` or `bento` is set. The spacer and separator elements are not rendered when rows are aligned. Alignment uses CSS subgrid; browsers without subgrid support show the regular layout.

```markdown
{{< card-group cols="3" gutter="3" align-rows=true >}}
    {{< card title="Starter" icon="fas seedling"
        subtitle="For individuals."
        highlight="**€0** per month" >}}

- One project
- Community support

    {{< /card >}}
    {{< card title="Team" icon="fas users"
        subtitle="For growing teams that share their projects."
        highlight="**€9** per user per month" >}}

- Unlimited projects
- Shared workspaces
- Priority support

    {{< /card >}}
    {{< card title="Enterprise" icon="fas building"
        subtitle="For organizations with *custom* needs, such as single sign-on and audits."
        highlight="**Custom pricing**" >}}

- Dedicated account manager
- Custom contracts

    {{< /card >}}
{{< /card-group >}}
```

Alignment also works with colored and bordered cards. The card's background and border wrap all six bands.

```markdown
{{< card-group cols="3" gutter="3" align-rows=true >}}
    {{< card color="primary" title="Starter"
        subtitle="For individuals."
        highlight="**€0** per month" >}}

- One project
- Community support

    {{< /card >}}
    {{< card color="primary" title="Team"
        subtitle="For growing teams that share their projects."
        highlight="**€9** per user per month" >}}

- Unlimited projects
- Shared workspaces
- Priority support

    {{< /card >}}
    {{< card color="primary" title="Enterprise"
        subtitle="For organizations with *custom* needs, such as single sign-on and audits."
        highlight="**Custom pricing**" >}}

- Dedicated account manager
- Custom contracts

    {{< /card >}}
{{< /card-group >}}
```

## Arguments

The shortcode supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `align` | select |  | `start` | Alignment of the headline, content, or icon. Supported values: [`start`, `center`, `end`]. |
| `align-rows` | bool |  |  | Aligns card parts across each visual row. Applies to stacked, non-scroll, non-bento groups only. Spacer and separator are not rendered when alignment is active. |
| `bento` | bool |  |  | Trigger to use a bento-style layout instead of default grid layout. |
| `body-style` | select |  | `full` | Body components of the element. Supported values: [`full`, `title`, `minimal`, `none`]. |
| `button` | bool |  |  | Flag indicating the elements should include a button that links to the provided address. |
| `button-icon` | bool |  |  | Show the cardReadMore theme icon on the button of stacked cards. Overrides the global main.cards.buttonIcon site setting. |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `color` | select |  |  | Theme color of the element. Supported values: [`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `white`, `black`, `body`, `body-tertiary`]. |
| `cols` | int |  | `3` | Number of grid columns. |
| `footer-style` | select |  | `none` | Footer components of the element, displayed in small caps. Supported values: [`full`, `category`, `date`, `publication`, `tags`, `none`]. |
| `gutter` | int |  | `4` | Gutter between columns in a group. |
| `header-style` | select |  | `full` | Header components of the element, displayed in small caps. Supported values: [`full`, `category`, `date`, `publication`, `tags`, `none`]. |
| `icon-rounded` | bool |  |  | Stack the icon in a round container. |
| `icon-style` | string |  |  | Icon style. |
| `link-icon` | bool |  |  | Show a hover icon to the right of the card title to signal a clickable card. Overrides the global main.cards.linkIcon site setting. Only applies to cards without an explicit button. Cascades to all child cards. |
| `link-type` | select |  | `button` | Style of the link. Supported values: [`button`, `link`]. |
| `loading` | select |  | `eager` | Image loading behavior. The loading of lazily loaded images is deferred until the image is within scrolling range of the viewport. This should reduce the initial loading time of the website. It is recommended to lazily load only those images that are below the page fold. Supported values: [`lazy`, `eager`]. |
| `orientation` | select |  | `stacked` | Placement of the thumbnail or icon. Supported values: [`stacked`, `horizontal`, `horizontal-sm`, `overlay`, `none`]. |
| `padding` | int |  | `3` | Padding of the content. |
| `portrait` | bool |  |  | Flag to adjust the image ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. Not applicable to vector graphics. |
| `ratio` | select |  |  | Ratio of the media asset. When the asset is an image, it is resized and cropped (not applicable to vector graphics). For video assets, the padding of the embedded frame is adjusted. When set to auto, the original aspect ratio is used. Supported values: [`1x1`, `3x1`, `3x2`, `4x3`, `16x9`, `21x9`, `auto`]. |
| `responsive` | bool |  | `true` | Flag indicating if the element should be responsive. |
| `scroll` | bool |  |  | Enables horizontal scrolling of the cards. By default, the card group wraps any cards beyond the amount of defined columns to a new line. When `scroll` is set to true, a horizontal scroll bar is added instead. |
| `separator` | bool |  |  | Flag to indicate a horizontal line should be added between items on small screens. |
| `subtle` | bool |  |  | Apply subtle theme colors. |
| `title` | string |  |  | Title of the element. If the element references a (local) page, the title overrides the referenced page's title. |
| `valign` | select |  |  | Defines the vertical card alignment, only applicable in bento layout. Supported values: [`start`, `center`, `end`]. |
| `wrapper` | string |  | `p-0` | Class attribute of the element's wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the `fa-wrapper` and `fa-fluid` attributes by default. |

In addition, the following arguments are passed to the individual cards.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `align` | select |  | `start` | Alignment of the headline, content, or icon. Supported values: [`start`, `center`, `end`]. |
| `align-rows` | bool |  |  | Aligns card parts across each visual row. Applies to stacked, non-scroll, non-bento groups only. |
| `alt` | string |  |  | Alternate text for the thumbnail, uses `title` by default. |
| `anchor` | select |  |  | Anchor of the image's crop box, defaults to anchor value set in `imaging` section of the site configuration (usually `Smart`). Supported values: [`TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, `Smart`]. |
| `body-style` | select |  | `full` | Body components of the element. Supported values: [`full`, `title`, `minimal`, `none`]. |
| `button` | bool |  |  | Flag indicating the elements should include a button that links to the provided address. |
| `button-icon` | bool |  |  | Show the cardReadMore theme icon on the button of a stacked card. Overrides the global main.cards.buttonIcon site setting. Horizontal cards always show the icon. Cascades to all child cards. |
| `button-label` | string |  |  | Label of the link button, defaults to the card title. |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `color` | select |  |  | Theme color of the element. Supported values: [`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `white`, `black`, `body`, `body-tertiary`]. |
| `exact` | bool |  |  | Renders the provided title as-is, without adjusting the case. Overrides the site's title case setting. |
| `footer-style` | select |  | `none` | Footer components of the element, displayed in small caps. Supported values: [`full`, `category`, `date`, `publication`, `tags`, `none`]. |
| `gutter` | int |  |  | Gutter between columns in a group. |
| `header-style` | select |  | `full` | Header components of the element, displayed in small caps. Supported values: [`full`, `category`, `date`, `publication`, `tags`, `none`]. |
| `highlight` | string |  |  | Emphasised line rendered between the subtitle and the card body, such as a price. |
| `href` | string |  |  | Address for the button or hyperlink. When set for a card group, a button is added if the list exceeds the maximum number of cards to display. |
| `icon` | string |  |  | Icon to include. You can use shorthand notation such as `fas sort` to include a Font Awesome icon. The argument also supports files with an `.svg` or `.json` extension. |
| `icon-rounded` | bool |  |  | Stack the icon in a round container. |
| `icon-style` | string |  |  | Icon style. |
| `link-icon` | bool |  |  | Show a hover icon to the right of the card title to signal a clickable card. Overrides the global main.cards.linkIcon site setting. Only applies to cards without an explicit button. Cascades to all child cards. |
| `link-type` | select |  | `button` | Style of the link. Supported values: [`button`, `link`]. |
| `orientation` | select |  | `stacked` | Placement of the thumbnail or icon. Supported values: [`stacked`, `horizontal`, `horizontal-sm`, `overlay`, `none`]. |
| `padding` | int |  | `3` | Padding of the content. |
| `path` | path |  |  | Path of the page that the element references. |
| `portrait` | bool |  |  | Flag to adjust the image ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. Not applicable to vector graphics. |
| `subtitle` | string |  |  | Short line rendered below the card title. |
| `subtle` | bool |  |  | Apply subtle theme colors. |
| `thumbnail` | path |  |  | Thumbnail image URL, displayed at the top or to the left of the element. |
| `title` | string |  |  | Title of the element. If the element references a (local) page, the title overrides the referenced page's title. |
| `wrapper` | string |  |  | Class attribute of the element's wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the `fa-wrapper` and `fa-fluid` attributes by default. |
