@material/card

Cards

Cards contain content and actions about a single subject.

For additional information, see the API.

Using cards

Installation

npm install @material/card

Styles

@use "@material/card";

@include card.core-styles;

In order to remain general-purpose and support e.g. images spanning the full width of the card, MDC Card does not include padding styles on the root element. When adding free-form text content to cards, padding should be set to 16px:

.my-card-content {
  padding: 16px;
}

Note: MDC Card's predefined classes for content areas (e.g. mdc-card__actions) take care of their own padding.

By default, cards expand horizontally to fill all available space, and vertically to fit their contents. If you'd like to maintain a consistent width and height across cards, you'll need to set it in your styles:

.my-card {
  height: 350px;
  width: 350px;
}

You can also place cards within layout containers, such as MDC Layout Grid or CSS Flexbox or Grid.

JavaScript

MDC Card itself does not require JavaScript. However, if you place interactive components inside your cards, you may want to instantiate ripples or other components. For example:

import {MDCRipple} from '@material/ripple';

const selector = '.mdc-button, .mdc-icon-button, .mdc-card__primary-action';
const ripples = [].map.call(document.querySelectorAll(selector), function(el) {
  return new MDCRipple(el);
});

Note: If your card includes any icon button toggles, you will want to instantiate MDCIconButtonToggle instead of MDCRipple.

Card

Card example

<div class="mdc-card">
  <!-- ... content ... -->
</div>

Note: MDC Card is designed to accommodate a wide variety of use cases. See the Card Contents section for information on helpers for specific types of content within cards.

Other variants

Outlined card

By default, cards are elevated with no outline. You can render unelevated, outlined cards instead by adding the mdc-card--outlined modifier class.

<div class="mdc-card mdc-card--outlined">
  <!-- ... content ... -->
</div>

Card contents

MDC Card can be used for a wide variety of use cases, but it includes styles for a few common ones.

Primary action

If a majority of the card (or even the entire card) should be actionable, you can add the mdc-card__primary-action class to the region to give it MDC Ripple styles. You should also assign tabindex="0" to ensure it can also be interacted with via keyboard.

<div class="mdc-card">
  <div class="mdc-card__primary-action" tabindex="0">
    <!-- content within actionable area -->
    <div class="mdc-card__ripple"></div>
  </div>
  <!-- ... content ... -->
</div>

Note: We recommend avoiding adding other actionable items within mdc-card__primary-action, due to the overlapping effect of multiple nested elements with ripple and states applied at once.

Rich media

This area is used for showing rich media in cards, and optionally as a container. Use the mdc-card__media CSS class and the optional modifier classes.

<div class="my-card__media mdc-card__media mdc-card__media--16-9">
  <div class="mdc-card__media-content">Title</div>
</div>

.my-card__media {
  background-image: url("pretty.jpg");
}

Actions

This area is used to show different actions the user can take, typically at the bottom of a card. It's often used with buttons:

<div class="mdc-card__actions">
  <button class="mdc-button mdc-card__action mdc-card__action--button">
    <div class="mdc-button__ripple"></div>
    <span class="mdc-button__label">Action 1</span>
  </button>
  <button class="mdc-button mdc-card__action mdc-card__action--button">
    <div class="mdc-button__ripple"></div>
    <span class="mdc-button__label">Action 2</span>
  </button>
</div>

It can also be used with icon buttons:

<div class="mdc-card__actions">
  <button class="mdc-icon-button mdc-card__action mdc-card__action--icon"
     aria-pressed="false"
     aria-label="Add to favorites"
     title="Add to favorites">
   <i class="material-icons mdc-icon-button__icon mdc-icon-button__icon--on">favorite</i>
   <i class="material-icons mdc-icon-button__icon">favorite_border</i>
  </button>
  <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="Share">share</button>
  <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="More options">more_vert</button>
</div>

Be sure to include the mdc-card__action class on every action for correct positioning. In addition, button icons should use the mdc-card__action--button class, and icon actions should use the mdc-card__action--icon class.

To have a single action button take up the entire width of the action row, use the --full-bleed modifier on the row:

<div class="mdc-card__actions mdc-card__actions--full-bleed">
  <a class="mdc-button mdc-card__action mdc-card__action--button" href="#">
    <div class="mdc-button__ripple"></div>
    <span class="mdc-button__label">All Business Headlines</span>
    <i class="material-icons mdc-button__icon" aria-hidden="true">arrow_forward</i>
  </a>
</div>

To display buttons and icons in the same row, wrap them in mdc-card__action-buttons and mdc-card__action-icons elements:

<div class="mdc-card__actions">
  <div class="mdc-card__action-buttons">
    <button class="mdc-button mdc-card__action mdc-card__action--button">
      <div class="mdc-button__ripple"></div>
      <span class="mdc-button__label">Read</span>
    </button>
    <button class="mdc-button mdc-card__action mdc-card__action--button">
      <div class="mdc-button__ripple"></div>
      <span class="mdc-button__label">Bookmark</span>
    </button>
  </div>
  <div class="mdc-card__action-icons">
   <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="Share">share</button>
    <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="More options">more_vert</button>
  </div>
</div>

Icons

We recommend using Material Icons from Google Fonts:

<head>
  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
</head>

However, you can also use SVG, Font Awesome, or any other icon library you wish.

Combined example

The following is an example incorporating all of the above elements:

<div class="mdc-card">
  <div class="mdc-card__primary-action">
    <div class="mdc-card__media mdc-card__media--square">
      <div class="mdc-card__media-content">Title</div>
    </div>
    <!-- ... additional primary action content ... -->
    <div class="mdc-card__ripple"></div>
  </div>
  <div class="mdc-card__actions">
    <div class="mdc-card__action-buttons">
      <button class="mdc-button mdc-card__action mdc-card__action--button">
        <div class="mdc-button__ripple"></div>
        <span class="mdc-button__label">Action 1</span>
      </button>
      <button class="mdc-button mdc-card__action mdc-card__action--button">
        <div class="mdc-button__ripple"></div>
        <span class="mdc-button__label">Action 2</span>
      </button>
    </div>
    <div class="mdc-card__action-icons">
      <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="Share">share</button>
      <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="More options">more_vert</button>
    </div>
  </div>
</div>

Non-semantic content

It can occasionally be useful to add non-semantic elements to a card. For instance, some implementations might do this to add an overlay layer.

In this case, it's important to delineate between semantic (real) content and non-semantic content added by the implementation. To achieve this, simply wrap the semantic content in an mdc-card__content element. The non-semantic content can remain at the card's top level:

<div class="mdc-card">
  <div class="mdc-card__content">
    <!-- ... semantic content ... -->
  </div>
  <!-- ... non-semantic content ... -->
</div>

API

CSS classes

CSS Class	Description
mdc-card	Mandatory. The main card element.
mdc-card--outlined	Optional. Removes the shadow and displays a hairline outline instead.
mdc-card__primary-action	Optional. The main tappable area of the card. Typically contains most (or all) card content except mdc-card__actions. Only applicable to cards that have a primary action that the main surface should trigger.
mdc-card__ripple	Optional. The element that shows the ripple styling. This is mandatory if mdc-card__primary-action is used. Only applicable to cards that have a primary action that the main surface should trigger.
mdc-card__media	Optional. Media area that displays a custom background-image with background-size: cover.
mdc-card__media--square	Optional. Automatically scales the media area's height to equal its width.
mdc-card__media--16-9	Optional. Automatically scales the media area's height according to its width, maintaining a 16:9 aspect ratio.
mdc-card__media-content	Optional. An absolutely-positioned box the same size as the media area, for displaying a title or icon on top of the background-image.
mdc-card__actions	Optional. Row containing action buttons and/or icons.
mdc-card__actions--full-bleed	Optional. Removes the action area's padding and causes its only child (an mdc-card__action element) to consume 100% of the action area's width.
mdc-card__action-buttons	Optional. A group of action buttons, displayed on the left side of the card (in LTR), adjacent to mdc-card__action-icons.
mdc-card__action-icons	Optional. A group of supplemental action icons, displayed on the right side of the card (in LTR), adjacent to __action-buttons.
mdc-card__action	Optional. An individual action button or icon.
mdc-card__action--button	Optional. An action button with text.
mdc-card__action--icon	Optional. An action icon with no text. We recommend using Material Icons from Google Fonts.
mdc-card__content	Optional. Used to delineate the card's semantic contents from any non-semantic elements (e.g., those used to implement an overlay).

Sass mixins

Mixin	Description
fill-color($color)	Sets the fill color of a card.
outline($color, $thickness)	Sets the color and thickness of a card's outline (but does not remove its shadow).
shape-radius($radius, $rtl-reflexive)	Sets the rounded shape to card with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
media-aspect-ratio($x, $y)	Maintains the given aspect ratio on a mdc-card__media subelement by dynamically scaling its height relative to its width.

Changelog

14.0.0 (2022-04-27)

Bug Fixes

• button: update HCM shim to use the existing focus-ring (a657abb)
• checkbox: Add explicit system color for checkmark in HCM. (8c4da22)
• checkbox: move forced-colors theme out of static styles (bbd1126)
• checkbox: Update checkbox theme styles mixin to accept css vars (c14e977)
• chips: Fix typography selector in GMDC-Wiz chips theming (43c7d87)
• datatable: Adjust data table last row border-radius to support setting row background-color. (ba78e87)
• dialog: Render dividers in Firefox 94 on Windows HCM (fae6c65)
• dialog: Set default z-index for close button in FloatingSheet dialog. (3366a71)
• fab: Add focus ring in HCM. (d57ec74)
• focus-ring: add 2d padding customizability, RTL bugfix (f81fb1d)
• focus-ring: box-sizing bugfix to content-box. If box-sizing border-box is inherited the ring spacing will collapse. (e58552c)
• focus-ring: ignore pointer events (3ef470e)
• focus-ring: RTL bugfix (e00181e)
• iconbutton: Fixed max width and height for high contrast mode focus ring on icon buttons. Display only in forced colors mode. (cf42927)
• iconbutton: Set icon button ripple z-index to -1. (586e740)
• list: Improve a11y for multi-select lists (9736ddc)
• list: Remove conflicting validation for checkbox list in setEnabled (353ca7e)
• list: Update lastSelectedIndex when toggling a checkbox range (dcba26f)
• menusurface: Add a getOwnerDocument() method to MDCMenuSurfaceAdapter to provide a reference to the document that owns the menu surface DOM element. (3486659)
• radio: Fix disabled state in Firefox Windows high contrast mode (23043ac)
• radio: Modify theme styles Sass mixin validation to validate only keys (390220e)
• select: Add border to select menu in HCM. (5d80969)
• select: revert down/up arrow on anchor changing selected index (43d08ba)
• slider: Fix bug where secondary click moves slider thumb. (3ab9565)
• slider: Fix IE11 bug - unset is unsupported in IE. (f460e23)
• slider: In updateUI, fix behavior to match jsdoc claim that when thumb param is undefined it updates both thumbs. Input attributes were not being updated at all. (cc4ed13)
• slider: Make the slider errors easier to debug by providing all relevant values in the error message. (8687937)
• snackbar: address Trusted Types violation (cbd9358)
• tooltip: Adjusts logic in validateTooltipWithCaretDistances method. (3e30054)
• typography: Fixes typography theme-styles mixin... the value being retreived from the $theme map and css property name was swapped. The mixin would request font-size/font-weight/letter-spacing from the $theme map (which expects size/weight/tracking)... so these values would always be null. (32b3913)
• Remove /** @override */ tags from TypeScript code. (c3cdff0)
• Simplify MDCAttachable interface to be any object (Function) that has attachTo. (05db65e)
• Snackbar action button ripple color is applied to the ripple element. (4e66fb2)
• Work around bug in Sass (037285f), closes sass/sass#3259
• switch: Restore Firefox 94 HCM outlines (39cf14b)
• textfield: Fix breaking tests due to no valid pointerId being associated with pointer events. (15db4f1)
• tooltip: Only sends notification of a tooltip being hidden if showTimeout is not set (indicating that this tooltip is about to be re-shown). (6ca8b8f)

Features

• banner: Add disableAutoClose params for both banner actions to prevent the banner buttons from automatically closing the banner. Add adapter #notifyActionClicked method. (b094eaa)
• chips: add focus ring styles (783f6fd)
• chips: Added elevation tint layer color support in chips (c78ff04)
• data-table: separate table structure into its own mixin (9f9d928)
• dialog: Add styling for floating sheets (78305b6)
• dialog: Add styling for floating sheets with content padding (3e20c1d)
• Dialog: Adds an API to hide the header for GMDC Fullscreen Dialog in non-fullscreen mode (ab4aba1)
• Dialog: Adds an API to set custom position for GMDC Dialog (ea9b5b4)
• Dialog: Adds an API to set custom z-index for GMDC Dialog (96ea061)
• focus-ring: added a new mixin so we can override just the focus-ring color (641ed08)
• focus-ring: added a new mixin so we can override just the focus-ring radius (7321d62)
• iconbutton: Add link icon button Sass. (9803d2d)
• mdc-list: introduce selection change event (7d8ea46)
• menu: allow preferentially opening surface below anchor (261f2db)
• MenuSurface: Add opening event for menus. (53b3cad)
• select: Add theming mixin boilerplate code to select (ae8a6a3)
• select: Add validation getter methods. (bdf1d37)
• select: Added theme mixins to MDC select (dcfe49c)
• slider: Add minRange param to range sliders to request a minimum gap between the two thumbs. (8fffcb5)
• slider: Add an option to hide focus styles after pointer interaction. (ec54d90)
• slider: Keep the slider value indicator within the bounds of the slider if possible. (c047f7c)
• state: make context aware (b2fe352)
• switch: Add high contrast mode focus ring to switch (f31a833)
• text-field: Add theming mixin boilerplate code to text-field (eb382f3)
• text-field: Added theme mixins to MDC text field (344d528)
• textfield: adding input-font-size mixin (207230e)
• theme: allow custom property strings in theme.validate-theme() (4e372fb)
• add new class and mixin for open state of a menu item (9a02b6e)
• Indicate which thumb valueToAriaValueTextFn and valueToValueIndicatorTextFn functions are called for. (b6510c8)
• textfield: adding input-font-family mixin (991fb99)
• Describe how to add child lists into a list item. (758ce31)

BREAKING CHANGES

• MenuSurface: Adds #notifyOpening method to menu surface adapter.

PiperOrigin-RevId: 444830518

• slider: Adds #getValueIndicatorContainerWidth method to slider adapter.

PiperOrigin-RevId: 419837612