The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

Card

Figma GitHub

A block container that provides styling for elevation, border, and background.

Usage

When to use

Use a card container to help build more consistently styled cards.

Types

Static cards

Static cards may contain interactive elements but must not be actionable or interactive on their own. They should not have any shadows applied to them, so that they can be differentiated from an interactive card.

A static card titled "Billing summary" with an info notification and a link.

Interactive cards

Interactive cards are actionable, e.g., they can be hovered over, clicked, or focused on.

Don’t

If you're using an interactive element (like an <a> or <button>) as the main content wrapper inside Card::Container, avoid placing other interactive elements inside it. This kind of nesting creates accessibility issues—particularly for screen reader users—because nested interactive elements can't be reliably accessed or operated.

An interactive card with a table with links and buttons within causing a nested interactive.

Do

When the card is interactive, only static elements should be contained within it.

An interactive card with a table with links and buttons within.

Levels

example of card styles for various levels, including: base, mid, and high

Base

Use for static cards.

Mid

Use for the rested (default) and active (pressed) states of interactive cards.

High

Use for the raised (hover) state of interactive cards.

Border

Card containers come with or without borders.

example of card styles with and without borders

Background

There are two backgrounds available: neutral-primary and neutral-secondary.

example of card styles in two background colors: neutral-primary and neutral-secondary

We recommend the following spacing options for cards:

example of card styles for recommended spacing options: 16px, 24px, 16px 24px, 24px 16px

  • 16px all around
  • 24px all around
  • 16px top/bottom; 24px left/right
  • 24px top/bottom; 16px left/right

Consumer responsibility

The layout of the Card itself, and its content, is left to the consumer of the component. The Hds::Card::Container is nothing more than a block container—a <div>—that provides styling for the elevation, border, and background. Sizing of the card, internal padding, and content alignment are all the consumer’s responsibility.

How to use this component

[Your content here] 
<Hds::Card::Container @level="mid" @hasBorder={{true}}>
  [Your content here]
</Hds::Card::Container>

To style the Cards, you can add an external element that wraps the Card, with a custom class that controls the width of the wrapper itself and an internal element that wraps the content and applies padding around it (resulting in visual internal padding for the Card) and aligns the text to the center.

Alternatively, you could use the Card Containers in a CSS flex or grid container.

HTML tag

To specify which HTML tag to use to render the component, use the @tag argument. The default tag is a div but you can optionally render the Card as an li to be used within a list.

Note: If you choose to use the Card as a list item, you must wrap it either in a ul or ol tag for the markup to be valid. Also note that you are responsible for the related styling for the list and list items.

  • Card item 1
  • Card item 2
  • Card item 3 
<ul class="doc-card-list-demo">
  <Hds::Card::Container @tag="li" @hasBorder={{true}} class="doc-card-list-demo__item">
    Card item 1
  </Hds::Card::Container>

  <Hds::Card::Container @tag="li" @hasBorder={{true}} class="doc-card-list-demo__item">
    Card item 2
  </Hds::Card::Container>

  <Hds::Card::Container @tag="li" @hasBorder={{true}} class="doc-card-list-demo__item">
    Card item 3
  </Hds::Card::Container>
</ul>

Interactive states

The @level, @levelHover, and @levelActive arguments can be used to declare the specific elevation of the Card for each interactive state. Following the guidelines, this example transitions between mid → high → mid elevation for the corresponding interactive states; default → hover → active.

[Your static content here] 
<div class="doc-card-interactive-demo">
  <Hds::Card::Container @level="mid" @levelHover="high" @levelActive="mid" @hasBorder={{true}}>
      <a href="#">
        [Your static content here]
      </a>
  </Hds::Card::Container>
</div>

Using SCSS, the .doc-card-interactive-demo class would look something like this:

.doc-card-interactive-demo {
  .hds-card__container {
    a {
      display: block;
      padding: 16px;
      border-radius: inherit;

      &:focus {
        outline: none;
        box-shadow: var(--token-focus-ring-action-box-shadow);
      }
    }
  }
}

This example implements a basic interactive card which uses a link to wrap the entirety of the static content area. For further assistance on implementing interactive cards, contact the Design System Team.

Component API

Card::Container

level enum
  • base (default)
  • mid
  • high
Controls the level of elevation (amount of "shadow" effect).
levelHover enum
  • base
  • mid
  • high
Controls the level of elevation for the :hover state.
levelActive enum
  • base
  • mid
  • high
Controls the level of elevation for the :active state.
background enum
  • neutral-primary (default)
  • neutral-secondary
Controls the background color.
hasBorder boolean
  • false (default)
Controls whether or not the Card has a visible external border.
overflow enum
  • visible (default)
  • hidden
Controls the "overflow" property for the component.
tag enum
  • div (default)
  • li
The HTML tag that wraps the Card content.
…attributes
This component supports use of ...attributes.

Conformance rating

Conditionally conformant

By default, the Card container component has @overflow="hidden" applied to it. This means you may need to handle cases where text is truncated, to make it accessible for keyboard-only users.

If the Card tag argument is set to li, it must be contained within either a ul or ol parent element in order for the HTML markup to be valid.

Additionally, if the component is altered to be an interactive element, and also contains interactive elements like links or buttons, it can cause a conformance failure for having nested interactive elements.

To implement accessible interactive cards, a helpful resource is the "Inclusive Components" blog on Cards.

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.18.1

Add tag argument to choose between using a div tag (the default) or an li tag

4.10.0

Fixed the HdsCard type reexport to reflect correct component name HdsCardContainer. If you are importing HdsCard types, update it to HdsCardContainer.

On this page: