# dds-card



<!-- Auto Generated Below -->


## Overview

A slotted surface that groups related content, with optional header and footer regions. It is a generic container to assistive technology; set `role` and `aria-*` on the host where the content has meaning. Set `href` to make the whole card a link, and name it with `aria-label`.

## Usage

### Card

# dds-card

#### A card with a header and footer

Content goes in the default slot. Add `slot="header"` to place content above it and `slot="footer"` to place content below it. A card with no header or footer content leaves no gap where they would be.

```html
<dds-card>
  <dds-heading slot="header" as="h3">Campaign overview</dds-heading>
  <dds-text>Performance summary for Q1 media activations.</dds-text>
  <dds-stack slot="footer" direction="inline" gap="s">
    <dds-button>View report</dds-button>
    <dds-button>Share</dds-button>
  </dds-stack>
</dds-card>
```

#### Surface

`padding`, `background`, `border` and `borderColor` set the card's surface and take the same values as `dds-box`. A card defaults to `padding="m"`, `background="1"` and `border="s"`. Set `border="none"` for a borderless card, or `borderColor` to change its outline.

```html
<dds-card padding="l" background="2" border-color="6">
  <dds-text>A roomier, tinted card with a darker outline.</dds-text>
</dds-card>
```

#### Cards in a layout

A card is not a layout container and does not arrange cards beside each other. Place cards in a `dds-stack` or `dds-grid` to lay them out.

```html
<dds-stack direction="inline" wrap gap="m">
  <dds-card><dds-text>First card</dds-text></dds-card>
  <dds-card><dds-text>Second card</dds-text></dds-card>
</dds-stack>
```

#### Accessibility

A card is a generic container to assistive technology. Where it groups content that has meaning, set `role` and `aria-*` on the card itself. `aria-label` has no effect without a `role`. A card is not interactive unless it has an `href`; see [A card that links](#a-card-that-links). To add a separate action to a card without linking the whole card, put a `dds-link` or `dds-button` inside it.

```html
<dds-card role="group" aria-label="Campaign overview">
  <dds-text>Performance summary for Q1 media activations.</dds-text>
</dds-card>
```

#### A card that links

Set `href` to make the whole card a link. The card's accessible name comes only from `aria-label` on the card, so every linked card needs one. No slot names the link, and `aria-labelledby` does not work because an id reference cannot cross the card's shadow root. A linked card with no `aria-label` is an unnamed link. `aria-current` and other `aria-*` attributes on the card reach the link as well.

```html
<dds-card href="/reports/q1" aria-label="Campaign overview">
  <dds-heading slot="header" as="h3">Campaign overview</dds-heading>
  <dds-text>Performance summary for Q1 media activations.</dds-text>
</dds-card>
```

Do not set `role` on a card that has an `href`. The `aria-label` would be announced for both the card and the link.

#### Opening a link in a new tab

Set `external` to open the link in a new tab. The card shows no icon, so say so in the `aria-label` or in the card's content.

```html
<dds-card
  href="https://dentsu.com"
  external
  aria-label="Dentsu, opens in a new tab"
>
  <dds-text>Visit dentsu.com</dds-text>
</dds-card>
```

#### Actions inside a linked card

A `dds-button`, `dds-link`, `a` or `button` placed directly in the card's `header`, default or `footer` slot stays clickable on top of the card's link. Interactive elements nested deeper, inside a wrapper you slot in, are covered by the link and cannot be clicked.

```html
<dds-card href="/reports/q1" aria-label="Campaign overview">
  <dds-heading slot="header" as="h3">Campaign overview</dds-heading>
  <dds-button slot="footer">Share</dds-button>
</dds-card>
```

#### Client-side routing

To route within a single-page app, listen for `click` on the card and cancel the navigation. Modified clicks such as cmd-click and middle-click still open the link natively, so skip routing when one is held.

```html
<dds-card id="report" href="/reports/q1" aria-label="Campaign overview">
  <dds-text>Performance summary for Q1 media activations.</dds-text>
</dds-card>

<script>
  document.getElementById("report").addEventListener("click", (event) => {
    if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
      return;
    event.preventDefault();
    router.push("/reports/q1");
  });
</script>
```



## Properties

| Property      | Attribute      | Description                                                                                                                                              | Type                                                      | Default     |
| ------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| `background`  | `background`   | The card's surface colour, as a step on the surface scale.                                                                                               | `"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "none"` | `"1"`       |
| `border`      | `border`       | The border width. The border is always solid.                                                                                                            | `"m" \| "none" \| "s"`                                    | `"s"`       |
| `borderColor` | `border-color` | The border colour, as a step on the border scale. Has no effect unless `border` is set.                                                                  | `"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| undefined`     | `undefined` |
| `external`    | `external`     | Opens the link in a new tab. Has no effect without `href`.                                                                                               | `boolean`                                                 | `false`     |
| `href`        | `href`         | The URL the whole card links to. The link takes its accessible name from `aria-label` on the card, since `aria-labelledby` cannot cross the shadow root. | `string \| undefined`                                     | `undefined` |
| `padding`     | `padding`      | The space between the card's edge and its content.                                                                                                       | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs"`    | `"m"`       |


## Slots

| Slot       | Description                       |
| ---------- | --------------------------------- |
|            | The card's content.               |
| `"footer"` | Content below the card's content. |
| `"header"` | Content above the card's content. |


## Shadow Parts

| Part     | Description               |
| -------- | ------------------------- |
| `"root"` | The surface, a `dds-box`. |


## Dependencies

### Depends on

- [dds-box](../box)
- [dds-stack](../stack)

### Graph
```mermaid
graph TD;
  dds-card --> dds-box
  dds-card --> dds-stack
  style dds-card fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*