v1.0.0 | View in Storybook
When to use
Cards group related content and actions about a single subject into a distinct, flexible container.
- Presenting heterogeneous content types together (e.g., image, title, summary text, metadata, badge, button).
- Structuring items in scannable, multi-column grid layouts (e.g., blog posts, product catalogs, user profiles, dashboard widgets).
- Serving as a entry-point preview that routes users to a detailed full-page view.
When to use something else
- Data Tables: Use when users need to perform line-by-line text comparisons, sort by specific attributes, or scan large datasets.
- Lists: Use for simple, homogeneous text items without heavy visual hierarchy or individual media elements.
- Dialogs / Drawers: Use when triggering primary workflows, multi-step forms, or critical decision-making tasks rather than content browsing.
Dos and don’ts
- Do focus each card on a single entity or subject.
- Do use consistent visual height and media ratios across grid items.
- Do provide clear hover and focus indicators for interactive Cards.
- Do truncate long description text to preserver layout grid balance.
- Don’t nest Cards inside other Cards.
- Don’t overload Cards with competing primary actions or extensive body text.
- Don’t Embed inline links or Buttons inside a Card that is already fully clickable.
- Don’t use Cards purely for background styling or wrapping single text paragraphs.
Behavior
- Click targets: If the Card container itself is actionable, make the entire surface area trigger the primary action. If the Card contains multiple distinct actions (e.g., Bookmark, Share, View Details), make secondary controls individual target Buttons and keep the container static to avoid conflicting tap zones.
- Visual states: Include explicit visual feedback for Default, Hover (subtle elevation rise or border highlight), Focus-Visible (accessible focus ring for keyboard navigation), and Pressed states.
- Responsive layout: Cards should adjust fluidly—scaling column spans across desktop break-points and dropping down to a single-column, full-width stack on mobile screens.
Anatomy
Each section of the Card is optional, but it is highly recommended to use a header to ensure a clear hierarchical relationship among content within the Card.
While not restricted, it is highly recommended to use a pre-configured header from Aura to create consistency across Cards in the product. Headers may consist of a combination of the following: leading icon, title, subtitle or status indicator and trailing content, which may be a Count or icon Buttons.
Body
Card bodies are entirely flexible to present relevant information and may consist of, but not limited to, media images, text, and Charts.
While not restricted, it is highly recommended to use a pre-configured footer from Aura to create consistency across Cards in the product. Footers may consist of Buttons or metadata.
Often used with
Button, Badge, Avatar, Separator; optional card-title typography; body slots for charts, lists, or form fields.
Accessibility
- Interactive containers: Avoid wrapping entire cards containing internal links or buttons inside a single parent
<a> tag. Make internal action links individual keyboard focus targets.
- Document outline: Structure internal title nodes (CardTitle) into logical heading sequences (
<h2> to <h4>) to support page landmark scanning.
Visual examples
The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.
Add a text-only footer to the Card when you need supplementary metadata—such as a timestamp or status line—without action buttons.
Use a Card footer with left and right slots when you need metadata on one side and actions on the other—for example, a date on the left and a Button on the right.
Place a Badge in the Card header to show status or category—such as Active, Draft, or Beta—without crowding the title.
Minimal
Use a minimal Card when you only need a bordered container for body content, without a header, footer, or actions.
With icon and title only
Use a Card with only an icon and title in the header when the content is self-explanatory and you want a compact, scannable list item.
With actions
Add action Buttons to the Card header or footer when users can act on the card directly—for example, Edit, Delete, or Open.
With icon and actions
Combine a header icon with Card actions when each item in a list has a distinct type and a primary action, such as opening a document or asset.
Place a Badge at the end of the Card header when status or count should align to the right—for example, unread count or severity.
With icon and header end
Use a Card with a header icon and end-slot content when the left icon identifies the item type and the right slot holds a Badge, menu, or action.
Content only
Use a content-only Card when the body is the focus and no header or footer is needed—for example, a chart, image, or data widget.
Grid layout
Arrange Cards in a grid when users browse a collection of items—such as assets, templates, or dashboards—and need equal visual weight per item.
Semantic headings
Set semantic heading levels on the Card title so the page outline stays correct when Cards appear inside sections with existing headings.
Header with only icon and right
Use a Card header with only an icon and right-slot content when the title is implied by context—for example, a thumbnail card with a menu button.
Use a Card header with only a description when a title would be redundant—for example, supplementary context below a page-level heading.
Long title and description clamping
Rely on title and description clamping when Card copy may be long, so list and grid layouts stay uniform without unpredictable row heights.
Multiple titles or descriptions
Avoid multiple titles or descriptions in a single Card header; this example documents edge-case layout when more than one text block is present.
Card actions align variants
Choose Card action alignment—start, end, or spread—based on whether actions should group with metadata or anchor to the trailing edge of the footer.
Use a footer with only an end slot when a single action or status label should sit on the right—for example, a View details link.
Use a footer with only a start slot when metadata or a secondary label belongs on the left—for example, Last updated or Created by.
Last modified on September 16, 2026
