# Card

Use the card shortcode to display a card that links to a content page.

## Overview

> [!IMPORTANT]
> Cards support inner content since release Added in v0.18.6
. As a result, references to the card shortcode must be closed or self-closed.

Use the `card` shortcode to display a card that links to a content page. When using a rich layout, the card includes a thumbnail (or icon) and a header. As an example, the following shortcode displays a horizontal card that links to the components overview. It includes a custom header and footer. You can use the [card-group shortcode](card-group)
 to align multiple cards and to position them in a grid.

### Inline content

Use `title`, `thumbnail`, `icon`, and inner content to define the card's content inline. You can add `padding` and `class` attributes to further refine the card's layout.

```markdown
{{< card padding="3" class="col-sm-12 col-lg-8 mx-auto mb-3" title="Title"
    icon="fa address-card" >}}
    This is the `body` of the card. It supports Markdown.
{{< /card >}}

{{< card padding="3" class="col-sm-12 col-lg-8 mx-auto" title="Title"
    thumbnail="img/placeholder.png" >}}
    This is the `body` of the card. It supports Markdown.
{{< /card >}}
```

### Referenced content

Set `path` to reference a content page within your site. The card uses the title and description of the referenced page, unless overruled.

```markdown
{{< card path="button" class="col-sm-12 col-lg-8 mx-auto mb-3" />}}
{{< card path="button" class="col-sm-12 col-lg-8 mx-auto" title="Custom Button Title" >}}
    Custom button body.
{{< /card >}}
```

### Inline content with a static reference

Set `href` and `button-label` to reference a static url with a button.

```markdown
{{< card padding="3" class="col-sm-12 col-lg-8 mx-auto" title="Hinode theme for Hugo"
    button-label="Visit the docs" href="https://gethinode.com" align="center" >}}
    Hinode is a production-ready Hugo theme built on Bootstrap 5.
    Open source, actively maintained, and built for developers.
{{< /card >}}
```

### Colored cards

Use the `color` argument to set the background color of the card. As an example, the following shortcodes display a plain card for each available color. The cards are embedded in a grid. The final two cards with the color `body` and `body-tertiary` are color-mode aware.

```markdown
{{< card-group cols="4" gutter="3" header-style="none" orientation="none" >}}
    {{< card color="primary" path="button" />}}
    {{< card color="secondary" path="button" />}}
    {{< card color="success" path="button" />}}
    {{< card color="danger" path="button" />}}
    {{< card color="warning" path="button" />}}
    {{< card color="info" path="button" />}}
    {{< card color="light" path="button" />}}
    {{< card color="dark" path="button" />}}
    {{< card color="white" path="button" />}}
    {{< card color="black" path="button" />}}
    {{< card color="body" path="button" />}}
    {{< card color="body-tertiary" path="button" />}}
{{< /card-group >}}
```

### Custom header

Use the `header-style` argument to customize the header of the card.

```markdown
{{< card-group cols="2" gutter="3" orientation="none" >}}
    {{< card path="button" header-style="full"  />}}
    {{< card path="button" header-style="publication" />}}
    {{< card path="button" header-style="tags" />}}
    {{< card path="button" header-style="none" />}}
{{< /card-group >}}
```

### Custom body

Use the `body-style` argument to customize the body of the card.

```markdown
{{< card-group cols="2" gutter="3" orientation="none" >}}
    {{< card path="button" header-style="tags" body-style="full"  />}}
    {{< card path="button" header-style="tags" body-style="title" />}}
    {{< card path="button" header-style="tags" body-style="minimal" />}}
    {{< card path="button" header-style="tags" body-style="none" />}}
{{< /card-group >}}
```

### Custom footer

Use the `footer-style` argument to customize the contents of the card.

```markdown
{{< card-group cols="2" gutter="3" header-style="none" orientation="none" >}}
    {{< card path="button" footer-style="full" />}}
    {{< card path="button" footer-style="publication" />}}
    {{< card path="button" footer-style="tags" />}}
    {{< card path="button" footer-style="none" />}}
{{< /card-group >}}
```

### Image placement

Use the `orientation` argument to customize the placement of the card's thumbnail or icon.

```markdown
{{< card title="Title" thumbnail="img/placeholder.png" orientation="stacked"
    padding="3" class="col-sm-12 col-lg-6 mx-auto mb-3" >}}
    This is the `body` of the card. It supports Markdown.
{{< /card >}}

{{< card title="Title" thumbnail="img/placeholder.png" orientation="horizontal"
    padding="3" class="col-sm-12 col-lg-6 mx-auto" >}}
    This is the `body` of the card. It supports Markdown.
{{< /card >}}
```

### Link icon

Use the `link-icon` argument to show a hover icon to the right of the card title, signalling
that the card is clickable. The icon is hidden by default and slides in when the card is
hovered or focused. It can be enabled globally via `main.cards.linkIcon` in your site
parameters, and overridden per card-group or individual card using the `link-icon` argument.
The icon only appears on cards that link to a page or URL and have no explicit button.

```markdown
{{< card-group cols="2" gutter="3" header-style="none" link-icon="true" >}}
    {{< card path="button" />}}
    {{< card path="link" />}}
{{< /card-group >}}
```

## Styling

The file `assets/scss/components/_card.scss` defines the Hinode-specific styling of the `card` shortcode. Check the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/components/card/#css) for additional styling options.

```scss
// add zoom animation with opacity change on card img hover
// source: https://stackoverflow.com/a/43816376

.card-img-bg {
    background-color: var(--#{$prefix}secondary-bg);
}

.card {
    --bs-card-border-radius: #{$theme-border-radius};
    --bs-card-inner-border-radius: #{$theme-border-radius};
    --bs-border-radius: #{$theme-border-radius};
    --bs-card-bg: transparent;
}

.card .card-img-wrap {
    overflow: hidden;
    position: relative;
}

.card .card-img-wrap:has(.card-img-top) {
  border-top-left-radius: var(--#{$prefix}card-inner-border-radius);
  border-top-right-radius: var(--#{$prefix}card-inner-border-radius);
}

.card .card-img-wrap:has(.card-img-bottom) {
  border-bottom-right-radius: var(--#{$prefix}card-inner-border-radius);
  border-bottom-left-radius: var(--#{$prefix}card-inner-border-radius);
}

.card-zoom {
    cursor: pointer;
}

.card-img-top {
    --bs-border-radius: #{$theme-border-radius};

    border-top-left-radius: var(--bs-border-radius) !important;
    border-top-right-radius: var(--bs-border-radius) !important;
}

.card-img-wrap img {
    transition: transform 0.25s ease;
    width: 100%;
}

.card-icon {
    color: $secondary;
}

.card-zoom::after .card-img-wrap img {
    content: "";
    position: absolute;
    inset: 0;
    background: rgba(255, 255, 255, 0.3);
    opacity: 0;
    transition: opacity 0.25s;
}

.card-zoom:hover .card-img-wrap img {
    transform: scale(1.1);
    opacity: 0.5;
}

.card-zoom:hover::after .card-img-wrap img {
    opacity: 1;
}

.card-emphasize {
    transition: 0.3s transform cubic-bezier(0.155, 1.105, 0.295, 1.12), 0.3s box-shadow, 0.3s -webkit-transform cubic-bezier(0.155, 1.105, 0.295, 1.12);
    cursor: pointer;
}

.card-emphasize:hover {
    transform: scale(1.01);
    box-shadow: 0 10px 20px rgba(0, 0, 0, 0.12), 0 4px 8px rgba(0, 0, 0, 0.06);
}

.card-minimal {
    border: none;
    font-weight: bold;

    &:hover,
    &:focus {
        text-decoration: underline;
    }
}

// stylelint-disable annotation-no-unknown
.card-body-link {
    color: $body-color if($enable-important-utilities, !important, null);
}

.card-body-margin {
    margin-bottom: $spacer * 1.5; // equals mb-4
}

@if $enable-dark-mode {
    @include color-mode(dark) {
        .card-body-link {
            color: $gray-500 if($enable-important-utilities, !important, null);
        }
    }
}

.card-img-overlay .card-body-link {
    margin-top: auto;
    overflow: hidden;
    text-overflow: ellipsis;
    display: -webkit-box;
    -webkit-line-clamp: 3;
    -webkit-box-orient: vertical;
}

.card-zoom .card-body-link {
    &:hover,
    &:focus {
        color: shade-color($primary, $link-shade-percentage) if($enable-important-utilities, !important, null);
    }
}

@if $enable-dark-mode {
    @include color-mode(dark) {
        .card-zoom .card-body-link {
            &:hover,
            &:focus {
                color: $primary-bg-subtle-dark if($enable-important-utilities, !important, null);
            }
        }
    }
}

// stylelint-enable annotation-no-unknown

// make tag-link and card-button clickable on top of the stretched-link.
.card .tag-link, .card .card-button {
    z-index: 2;
    position: relative;
}

.card-button-link {
    text-decoration: underline if($enable-important-utilities, !important, null);
}

// support horizontally scrollable card groups
.card-container-wrapper {
	position: relative;
}

div.card-container-wrapper::after {
	content: "";
	position: absolute;
	inset: 0;
	height: calc(100% - 2rem);
	background: linear-gradient(
		90deg, 
		var(--bs-body-bg) 0%,
		transparent 1.5rem,
		transparent calc(100% - 1.5rem),
		var(--bs-body-bg) 100%
	);
	pointer-events: none;
}

.card-container {
    padding-left: 1.5rem;
    padding-right: 1.5rem;
	gap: 1.5rem;
    margin-bottom: 2rem;
	scroll-snap-type: x proximity;
}

.card-block-1 {
    width: 80%;
	scroll-snap-align: center;
}

.card-block-2 {
    width: 40%;
	scroll-snap-align: center;
}

.card-block-3 {
    width: 27%;
	scroll-snap-align: center;
}

.card-block-4 {
    width: 20%;
	scroll-snap-align: center;
}

.card-block-5 {
    width: 16%;
	scroll-snap-align: center;
}

// Hover link icon: appears on card hover/focus to signal clickability
.card-link-icon {
    display: inline-flex;
    align-items: center;
    opacity: 0;
    transform: translateX(-4px);
    transition: opacity 0.2s ease, transform 0.2s ease;
    vertical-align: middle;
    font-size: 0.75em;
    margin-left: 0.25rem;
}

.card:hover .card-link-icon,
.card:focus-within .card-link-icon {
    opacity: 1;
    transform: translateX(0);
}
```

## 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`]. |
| `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-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`, `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`, `publication`, `tags`, `none`]. |
| `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. |
| `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. |