Card

Material Design 3 card surface for grouping related content and actions. Not intended for dense tabular data or long-form flows; use dedicated layout containers and lists for those cases.

Basic Usage

Use the default elevated card for general-purpose content grouping. Cards provide a single visual container for related media, text, and actions without requiring nested surfaces.

Card Title Subhead text

Card content is displayed in the default slot.

 
<ds-card variant="elevated">
  <span slot="title">Card Title</span>
  <span slot="subhead">Subhead text</span>
  <p>Card content...</p>
</ds-card>

Initial Value

Cards can render pre-populated media, content, and actions immediately.

Example card media Preloaded Card Data available on first render

This card starts with full media, text, and actions.

Action 
<ds-card variant="elevated">
  <img slot="media" src="..." alt="...">
  <span slot="title">Preloaded Card</span>
  <span slot="subhead">Data available on first render</span>
  <p>Card content...</p>
  <div slot="actions">
    <ds-button variant="text">Action</ds-button>
  </div>
</ds-card>

Variants/Formats

Choose visual emphasis with elevated, filled, or outlined variants.

Elevated

Default card with elevation.

 Filled

Card with surface container background.

 Outlined

Card with outline and minimal elevation.

 
<ds-card variant="elevated">...</ds-card>
<ds-card variant="filled">...</ds-card>
<ds-card variant="outlined">...</ds-card>

States

Cards support static and interactive states.

Static Card

Non-interactive display content.

 Interactive Card

Supports click and keyboard activation.

 
<ds-card variant="elevated">...</ds-card>
<ds-card variant="outlined" interactive>...</ds-card>

Interactive Example

Interactive cards emit ds-card:click.

Click Me Click or press Enter/Space

Event output updates below.
Waiting for event... 
const card = document.querySelector('#interactive-card');
card.addEventListener('ds-card:click', () => {
  console.log('Card activated');
});

API Reference

Attributes

Attribute Type Default Description
variant string elevated Visual style: elevated, filled, outlined
interactive boolean false Enables clickable behavior and keyboard activation

Properties

Property Type Description
variant string Gets or sets the card variant
interactive boolean Gets or sets interactive mode

Slots

Slot Description
media Media content shown at the top
title Card title text
subhead Supporting text below title
header-action Optional action in the header area
(default) Main card content
actions Bottom action area

Events

Event Detail Description
ds-card:click none Fired when interactive card is activated

CSS Parts

Part Description
(none) This component currently does not expose shadow parts

CSS Custom Properties

Property Description
--ds-card-touch-target-size Minimum interactive/action hit area (defaults to --ds-size-hit-area)
--ds-card-padding Card inner section padding
--ds-card-action-gap Spacing between actions

Accessibility

Keyboard Interaction

Key Context Expected Result
Tab Interactive card present Moves focus to the interactive card
Enter / Space Focus on interactive card Activates card and emits ds-card:click

Semantics

  • Interactive cards receive role="button" and tabindex="0".
  • Visible focus and state-layer feedback are applied on interaction.
  • Provide descriptive alt text for media content in the media slot.

Usage Guidelines

  • When to use: Group related content and actions for a single subject, such as a product, article, or profile summary.
  • When not to use: Avoid cards for highly dense data tables, long multi-step forms, or layouts where a full-width section is more readable.
  • Composition: Prefer elevated cards by default; use outlined for lower emphasis and filled for container contrast. Keep actions concise.
  • Common mistakes: Making every card interactive by default can create accidental taps. Only enable interactive when the full surface is a clear action target.