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

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


When to use

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


Static cards

Static cards may have interactive elements within them but are not actionable or interactive on their own.

Interactive cards

Interactive cards are actionable (e.g., it can be hovered, clicked, focused, etc.)



Use the base level for static cards.

example of base card style with borders


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

example of base card style with borders


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

example of base card style with borders


Card containers come with or without borders.


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

example of base card style with borders example of base card style with borders

We recommend the following spacing options for cards:

example of base card style with borders

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

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.

How to use this component

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

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.

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, 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.

Component API


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.
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.

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.


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