Skip to main content

Card

Content container with typed slots. A card packages a related set of information - image, title, supertitle, body, date, tags, metadata, actions, and icon - into a single, reusable surface consumers can drop into grids, lists, or hero sections. Slots accept either structured props (for default rendering) or raw HTML (for full control), so cards cover everything from simple teasers to rich composite listings.

Usage​

When to use

  • To present a single, self-contained piece of content (article teaser, product, profile, mission summary)
  • To create consistent teasers in a grid or list
  • To make a whole content block clickable via a stretched link

When not to use

  • For wide editorial layouts - use a section or a hero
  • For key-value facts with no visual surface - use a description list
  • For navigation items - use a navbar or link list

Do

  • Keep card titles concise and scannable
  • Use the same slots consistently across cards in the same grid
  • Use the stretched-link pattern to make cards fully clickable rather than wrapping the whole card in <a>

Don't

  • Don't nest interactive elements inside a fully clickable card without isolating them
  • Don't mix cards with different slot structures in a single grid
  • Don't overload a card with every slot - pick the ones that add value

The horizontal orientation reserves a fixed column for the image, so it needs a card wide enough to hold that column and a readable text column beside it. A narrower card stacks its content under a full-bleed image instead. The width is measured from the card itself, so a card reacts to the column it sits in rather than to the viewport - three cards across a grid stack, and the same card in a single-column layout does not.

API​

Slots​

SlotRequiredDescription
icon-Decorative icon mark, typically inline SVG.
media-Media markup: <img>, <picture>, <video>, or <svg>.
contentYesBody content markup (any flow HTML).
tags-Tags markup, typically a list of badge items, rendered in the footer.
actions-Actions markup, typically anchors or buttons, rendered in the footer.

Props​

PropTypeDefaultDescription
titlestring-Card title text.
title_idstring-id for the title element, referenced by aria-labelledby. Defaults to a generated value when omitted.
title_tagEnum: strong, p, h1, h2, h3, h4, h5, h6h3Tag used to render the title.
supertitlestring-Supertitle text rendered above the title.
datestring-Human-readable date display.
date_isostring-Machine-readable ISO 8601 date. Paired with date for accessible datetime rendering.
urlstring-Optional destination URL. When set, the title becomes a link covering the card.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.infoIntent-Informational message.
.warningIntent-Warning or caution.
.dangerIntent-Error, destructive, or critical.
.successIntent-Confirmation or completion.
.solidFill-Filled surface; background and border rendered.
.outlineFill-Bordered surface; transparent background.
.ghostFill-No surface; text or icon only.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.horizontalOrientationYesChildren flow along the horizontal axis.
.verticalOrientation-Children flow along the vertical axis.
.flatElevation-No elevation.
.raisedElevationYesSlight elevation.
.elevatedElevation-High elevation.

Examples​

Default​

Card with title, supertitle, image, content, and tags, in the default horizontal orientation - image on the left, content on the right, while the card is wide enough for both.

Vertical​

The vertical orientation stacks the content under a full-bleed image.

Clickable​

Full-area clickable card using the stretched link pattern.

With meta​

Card with meta key-value pairs and actions.

Accent​

The accent emphasis, which raises the surface and border above the neutral default.

With icon​

An icon in place of the media slot, for a card that leads with a symbol rather than a photograph.

Title as paragraph​

title_tag set to p, for a card that carries a title visually without claiming a heading level in the document outline.

Cards in grid​

Three cards across a grid leave each one too narrow for a side-by-side image column, so they stack. Hovering a card lifts it, and the whole surface is clickable through the title's stretched link.

Accessibility​

  • WCAG 2.2 AA
  • Card is a semantic grouping (<article>) so assistive tech can navigate between cards
  • Clickable cards use the stretched link pattern, not a wrapping <a>
  • Card title uses an appropriate heading level for the surrounding document outline
  • Focus indicator visible on all interactive children
  • collection - collection of cards and related components
  • callout - editorial emphasis within body copy
  • link - standalone link component