Skip to content
On this page

Card

A Card is used to group information and actions related to a single topic.

Cards can be clickable and offer a way to navigate to the content they represent (e.g. Wikipedia articles).

Guidelines

Using cards

Use the Card component when you need to present individual pieces of information such as articles. Use them to create lists, grids or as standalone elements in the page.

Avoid using cards when you have to display extensive content, multiple elements, or group unrelated topics together. In such cases, consider using a different component or layout.

Example of Codex Card with thumbnail, title, description, and supporting text.

Use short titles and descriptions along with visual reinforcements, such as thumbnails or icons, to ensure that the card's content is concise and easy to scan.

Specifications

Specification of Card.

Cards include the following items:

  1. Visual element (optional)
    Cards may include a thumbnail or an icon as a visual representation of the card’s content.
  2. Title
    A concise and descriptive title provides a brief description of the card content.
  3. Description
    A subtle text below the title provides more information about the element represented by the card.
  4. Supporting text (optional)
    An optional subtle text (with an optional icon) could be included to provide additional information about the card’s content.
  5. Links (optional)
    The description and/or the supporting text may contain links to either the element the Cards represent (e.g. Wikipedia articles), or to related content.

Refer to the Card component in Codex Figma.

Types

Depending on the visual content presented within the card, there are three distinct variations:

  1. Card with thumbnail
    This variation includes a thumbnail image as the primary visual element. You can use this card variation when you intend to showcase articles and their associated images.
  2. Card with icon
    In this version, an icon serves as the primary visual element, enhancing recognition. Icons help users quickly identify and associate cards with specific actions or topics.
  3. Card with only text
    This variation lacks any visual elements and relies solely on text and content for information. This option simplifies the card's design, focusing on textual information and content.

Example of types of Card.

Interaction states

Cards have the following visually separate states:

Interaction states of Card: default, hover, focus, and loading.

  1. Default
  2. Hover
  3. Focus
  4. Loading

Demos

Default

Card title Description Supporting text
NameValue
View
Reading direction

Adding the url prop will make the root element of the Card an anchor element.

Media

A Card can have either an icon or a thumbnail. Card text will be aligned to the top of the media, unless there is only a title, which will be aligned to the center of the media.

With icon

Card title Description

With thumbnail

Card title Description

Title only

Card title

Card groups

Cards will often be displayed in groups. There are two considerations for Card groups:

  • Layout: Layout styles for groups of Cards, e.g. margins or grid layout, must be added by the application. The example below adds some simple layout styles to a group of Cards.
  • Media consistency: As shown above, adding a thumbnail prop will display the thumbnail. For groups of Cards, you may want to display a thumbnail for each Card if available, and otherwise display a placeholder. To enable this behavior, add the forceThumbnail prop, as demonstrated below. The third item has no thumbnail and display a placeholder icon instead.

Maximum example

The example below contains a title, a description, a thumbnail image, and some "supporting text" (which contains an Icon as well as text content).

Note: When using an Icon component inside the Card's supporting-text slot, it is recommended to set the Icon size property to small.

Card titles should be fairly short, but will wrap onto a new line if the text becomes long enough Description text will commonly be longer than a single line, and will wrap onto new lines, expanding the height of the Card to accommodate the content. Supporting text should also be kept short, but if it is long, it will wrap onto a new line like the rest of the Card content.

Vue usage

Props

Prop nameDescriptionTypeDefault
urlIf provided, the Card will be a link to this URL.string''
iconIcon displayed at the start of the Card.Icon''
thumbnailThumbnail image data for the Card.Thumbnail|nullnull
forceThumbnailOption to force a thumbnail layout.

When set to true, the Card will display a Thumbnail. If a thumbnail prop was also provided, the thumbnail image will display. Otherwise, a placeholder icon will display.

This is useful when displaying groups of Cards when some of the cards have thumbnail images but some do not. forceThumbnail will provide a consistent layout for that group.

Note that this prop is not needed to display a thumbnail image: if the thumbnail prop is provided, it will display. This prop is only needed to enable the display of the thumbnail placeholder icon when the thumbnail prop is not provided.
booleanfalse
customPlaceholderIconOptional custom icon for the placeholder shown when forceThumbnail is true but no thumbnail is provided.

Defaults to the default placeholder icon set in the Thumbnail component.
Iconundefined

Slots

NameDescriptionBindings
titleCard title
descriptionCard description
supporting-textShort supporting text

CSS-only version

Markup structure

Card titleDescriptionSupporting text

To make the entire Card a link, use an <a> element and include the class cdx-card--is-link.

With media

Image

To add an image, add the following markup:

  • A <span> with the classes cdx-card--thumbnail and cdx-thumbnail
  • Inside of that <span>, add an empty <span> element with the class cdx-thumbnail__image, plus a custom CSS class that you can use to add a background-image rule (alternately, you can add the background-image rule via a style attribute on this <span>)

See the CSS-only Thumbnail documentation for more examples.

Card titleDescriptionSupporting text

Icon

To add an icon, add a <span> element with the class cdx-card__icon, plus a custom class that you can use to add a CSS-only icon.

Card titleDescriptionSupporting text

Card groups

See the documentation above for UX guidelines.