Skip to content

About

Card style based on Google Material color palette

Topics

Resources

Stars

401 stars

Watchers

21 watching

Forks

Repository files navigation

Material Cards

Material card component inspired by the Google Material color palette, built with vanilla JavaScript + SCSS.

Working demo on CodePen

See full preview

Installation

npm install material-cards

Quick start

<link rel="stylesheet" href="material-cards/css">

<article class="material-card Red">
  <h2>
    <span>Christopher Walken</span>
    <strong>
      <svg class="mc-icon" aria-hidden="true">
        <use href="material-cards/icons#mc-icon-star"></use>
      </svg>
      The Deer Hunter
    </strong>
  </h2>

  <div class="mc-content">
    <div class="img-container"></div>
    <div class="mc-description">...</div>
  </div>

  <a class="mc-btn-action" role="button" aria-label="Toggle details"></a>

  <div class="mc-footer">
    <h4>Social</h4>
    <a href="#" aria-label="Facebook">
      <svg class="mc-icon" aria-hidden="true">
        <use href="material-cards/icons#mc-icon-facebook"></use>
      </svg>
    </a>
  </div>
</article>

<script src="material-cards"></script>
<script>
  window.MaterialCards.initMaterialCards('.material-card');
</script>

API

initMaterialCards(target?, options?)

  • target: selector, single element, NodeList, or array of elements
  • options:
    • cardActivator (click or hover, default: click)
    • buttonSelector (default: .mc-btn-action)

mc-btn-action uses a built-in morph animation (hamburger -> X -> hamburger).

const cards = window.MaterialCards.initMaterialCards('.material-card', {
  cardActivator: 'click'
});

cards[0].open();
cards[0].close();
cards[0].toggle();
const isOpen = cards[0].isOpen();

Use mc-img-responsive for card images:

<img class="mc-img-responsive" src="..." alt="">

Events

Each card dispatches:

  • show.material-card
  • shown.material-card
  • hide.material-card
  • hidden.material-card
document.querySelector('.material-card').addEventListener('shown.material-card', (event) => {
  console.log(event.type, event.currentTarget);
});

Package exports

  • material-cards -> JS API (js/material-cards.js)
  • material-cards/css -> main CSS (dist/material-cards.css)
  • material-cards/css/auto-height -> auto-height CSS (dist/material-cards-auto-height.css)
  • material-cards/icons -> SVG sprite (assets/icons.svg)

Development

Use Node.js 24 LTS (24.11.0 or later) for the development toolchain.

npm install
npm run build

Experimental multi-framework packages (vNext)

The repository now includes a vNext scaffold with shared TypeScript models and framework adapters:

  • packages/core -> shared types and open-state contract
  • packages/react -> MaterialCard React component
  • packages/vue -> MaterialCard Vue 3 component
  • packages/svelte -> MaterialCard Svelte component

Core API (aligned across frameworks):

  • card: title, subtitle, description, image, links, actions
  • color: palette token (blue, teal, etc.) or custom
  • colorHex: explicit color override
  • isOpen + defaultOpen + onOpenChange

Icon strategy:

  • pass framework-native icon components (Icon/icon) for external libraries
  • or fallback to iconName for mapped/custom rendering

Styling strategy:

  • CSS is component-local (.module.css, Vue scoped style, Svelte style block)
  • consumers only load style for imported card component

Build and typecheck (vNext packages):

npm run build:vnext
npm run typecheck:vnext
npm run test:vnext
npm run smoke:vnext

Release/versioning (vNext packages):

npm run changeset
npm run version:vnext
npm run release:vnext

Build targets:

  • dist/material-cards.css
  • dist/material-cards-auto-height.css
  • js/material-cards.min.js

Local demos

  • demo/material-cards_simple.html
  • demo/material-cards_api.html
  • demo/material-cards_masonry.html

Demo images are stored in assets/images and use relative paths. See the demo guide for local preview and CodePen image URLs.

Migration notes

If you are upgrading from the old jQuery plugin, see MIGRATION.md.

Release

Follow RELEASE_CHECKLIST.md before publishing.

About

Card style based on Google Material color palette

Topics

Resources

Stars

401 stars

Watchers

21 watching

Forks

Releases

Packages

Used by

Contributors

Languages