Card

Released
Figma GitHub

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

Usage

When to use

Use a Card Container to help design more consistent cards.

Types

Static cards

A Static Card may have interactive elements within it, but is not itself actionable or interactive.

Interactive cards

The entirety of an Interactive Card is actionable (i.e., it can be hovered, clicked, focused, etc.)

Levels

Base

Use the base level for static cards.

Mid

For static cards use mid as the default level. For interactive cards use mid as the rested state.

High

For static cards use high for emphasis, but use sparingly. For interactive cards use high for the raised state.

Border

Border should be set to true or false.

Background

There are two backgrounds available: neutral-0 and neutral-50.

Spacing

Spacing options:

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

Usage

Invocation of the component would look something like this:

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

Just a container

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.

In this example we apply custom classes to control the layout of the card and its content:

[Your content here] 
<div class="my-custom-class-to-set-the-card-layout">
  <Hds::Card::Container @level="mid" @hasBorder={{true}}>
    <div class="my-custom-class-to-set-the-content-layout">
      [Your content here]
    </div>
  </Hds::Card::Container>
</div>

In this case we’ve added an external element that wraps the card, with a custom class that controls the width of the wrapper itself (but could also be a CSS flex or grid container, for example) 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.

Interactive states

At the moment, we do not recommend using the card component as an interactive element, although we may add this feature in the future. Despite this, some products have implemented designs that provide visual feedback to the user interacting with a card by changing the elevation style (on :hover or :active).

As a stopgap measure, we have introduced two specific arguments @levelHover and @levelActive to allow users to declare the specific "level" they want to use for each of these interactive states.

In the following example, the card transitions between these elevations mid → high → mid depending on these iteration states rest → hover → active:

[Your content here] 
<div class="my-custom-class-to-set-the-card-layout">
  <Hds::Card::Container @level="mid" @levelHover="high" @levelActive="mid" @hasBorder={{true}}>
    <div class="my-custom-class-to-set-the-content-layout">
      [Your content here]
    </div>
  </Hds::Card::Container>
</div>

Important: this is only an example and not a recommendation: if you have any doubt about which level to use for the different states, please speak with your product designer or the HDS team.

Component API

Name
level
Type
enum
Description
This controls the level of elevation ("shadow" visual effect). Notice: low and higher are not correct values for this component (by design).
Name
levelHover
Type
enum
Description
This controls the level of elevation on :hover state.
Name
levelActive
Type
enum
Description
This controls the level of elevation on :active state.
Name
background
Type
enum
Values
  • neutral-primary (default)
  • neutral-secondary
Description
This controls the background color. Notice: later we may decide/need to add more colors, but for now we have found only these two use cases.
Name
hasBorder
Type
boolean
Description
This controls if the card has a visual "edge", an external border (technically is an extra 1px shadow on top of the other drop shadows). Notice: the color of the border is pre-defined. If you need a custom border you have to wrap your content in an element and assign the border to it (in that case, remember to inherit the border radius).
Name
overflow
Type
enum
Values
  • hidden (default)
  • visible
Description
This controls if the main wrapper (who has a border-radius applied) has overflow = visible or hidden. We expect that this is needed in case part of the content (eg. a tooltip) needs to go beyond the bounding box of the card itself.
Name
…attributes
Description
...attributes spreading is supported on this component.

Elevation:

"level"

base
mid
high

"levelHover"

"levelActive"

Border:

Background:

Overflow:

hidden (default)
visible

Conformance rating

Conditionally conformant

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

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.

On this page: