Building a Card Component

Cards package content into neat, self-contained boxes. They're everywhere in modern UI — feature grids, team pages, link collections, content previews. In MDX, they let you break out of the plain-text look and present information visually.

Why Cards in MDX?

Markdown gives you headings, paragraphs, and lists. Sometimes that's not enough. You need visual grouping, clear boundaries between items, and a layout that feels polished. Cards do that. They take your docs from "wall of text" to "organized product page."

Component Source Code

Here's the full Card system with sub-components for header, body, footer, image, and grid:

Example

// components/Card.jsx import React from 'react'; // Base Card Component export function Card({ variant = 'elevated', children, className = '', href, onClick, as: Component = 'div', }) { const baseStyles = 'rounded-xl overflow-hidden transition-all duration-200'; const variantStyles = { elevated: 'bg-white dark:bg-gray-800 shadow-md hover:shadow-lg border border-gray-100 dark:border-gray-700', outlined: 'bg-transparent border-2 border-gray-200 dark:border-gray-600 hover:border-blue-400 dark:hover:border-blue-400', filled: 'bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700', }; const interactiveStyles = (href || onClick) ? 'cursor-pointer hover:scale-[1.02] active:scale-[0.98]' : ''; const Wrapper = href ? 'a' : Component; const wrapperProps = href ? { href, target: href.startsWith('http') ? '_blank' : undefined, rel: href.startsWith('http') ? 'noopener noreferrer' : undefined } : {}; return ( <Wrapper {...wrapperProps} onClick={onClick} className={` ${baseStyles} ${variantStyles[variant] || variantStyles.elevated} ${interactiveStyles} ${className} `} > {children} </Wrapper> ); } // Card Header Sub-component export function CardHeader({ children, className = '' }) { return ( <div className={`px-6 pt-6 pb-2 ${className}`}> {children} </div> ); } // Card Body Sub-component export function CardBody({ children, className = '' }) { return ( <div className={`px-6 py-4 ${className}`}> {children} </div> ); } // Card Footer Sub-component export function CardFooter({ children, className = '' }) { return ( <div className={`px-6 pb-6 pt-2 border-t border-gray-100 dark:border-gray-700 ${className}`}> {children} </div> ); } // Card Image Sub-component export function CardImage({ src, alt, aspectRatio = '16/9', className = '' }) { return ( <div className={`w-full overflow-hidden ${className}`} style={{ aspectRatio }} > <img src={src} alt={alt} className="w-full h-full object-cover" loading="lazy" /> </div> ); } // Card Grid Layout export function CardGrid({ children, columns = 3, gap = 6, className = '' }) { return ( <div className={` grid gap-${gap} grid-cols-1 md:grid-cols-2 lg:grid-cols-${columns} ${className} `} > {children} </div> ); }

Basic Card Usage in MDX

Here's a simple card with header, body, and footer:

mdx example

import { Card, CardHeader, CardBody, CardFooter } from '../components/Card';

# Feature Overview

<Card>
  <CardHeader>
    ## Getting Started
  </CardHeader>
  <CardBody>
    Learn how to set up your development environment and create
    your first MDX-powered application in under 5 minutes.
  </CardBody>
  <CardFooter>
    **Estimated time:** 5 minutes
  </CardFooter>
</Card>

Card with Image

Add a hero image at the top:

mdx example

import { Card, CardImage, CardBody } from '../components/Card';

<Card variant="elevated">
  <CardImage
    src="/images/tutorial-hero.jpg"
    alt="Screenshot of the completed tutorial project"
  />
  <CardBody>
    ## Complete Tutorial

    Build a full documentation site from scratch using MDX,
    Next.js, and Tailwind CSS.
  </CardBody>
</Card>

Card Grid Layout

CardGrid arranges cards into a responsive grid — stacks on mobile, fills columns on desktop:

mdx example

import { Card, CardBody, CardGrid } from '../components/Card';

# Our Features

<CardGrid columns={3}>
  <Card variant="outlined">
    <CardBody>
      ### ⚡ Fast
      Lightning-fast builds with incremental compilation
      and smart caching strategies.
    </CardBody>
  </Card>

  <Card variant="outlined">
    <CardBody>
      ### 🔐 Secure
      Built-in security best practices with automatic
      vulnerability scanning.
    </CardBody>
  </Card>

  <Card variant="outlined">
    <CardBody>
      ### 📱 Responsive
      Mobile-first design that looks great on every
      device and screen size.
    </CardBody>
  </Card>
</CardGrid>

Card Variants

Elevated Card (Default)

Uses box shadows for a "floating" look. Shadow deepens on hover:

mdx example

<Card variant="elevated">
  <CardBody>
    This card appears to float above the page with a subtle shadow
    that intensifies on hover.
  </CardBody>
</Card>

Outlined Card

Borders instead of shadows. Flatter, more minimal:

mdx example

<Card variant="outlined">
  <CardBody>
    This card has a visible border and transparent background.
    On hover, the border color transitions to blue.
  </CardBody>
</Card>

Filled Card

Subtle background color to stand out from the page:

mdx example

<Card variant="filled">
  <CardBody>
    This card has a light gray background that differentiates
    it from the surrounding content.
  </CardBody>
</Card>

Clickable Cards (Link Cards)

Pass href to make the whole card a link:

mdx example

<CardGrid columns={2}>
  <Card href="/docs/getting-started" variant="outlined">
    <CardBody>
      ### 📖 Documentation
      Full guides and API references for every feature.
    </CardBody>
  </Card>

  <Card href="https://github.com/example/repo" variant="outlined">
    <CardBody>
      ### 🐙 GitHub
      View source code, report issues, and contribute to the project.
    </CardBody>
  </Card>
</CardGrid>

Props API Documentation

Card Props

Prop	Type	Default	Description
`variant`	`'elevated' \	'outlined' \	'filled'`	`'elevated'`	Visual style of the card
`children`	`ReactNode`	required	Card content (use sub-components for structure)
`href`	`string`	`undefined`	Makes the entire card a link
`onClick`	`function`	`undefined`	Click handler for interactive cards
`as`	`ElementType`	`'div'`	HTML element to render as
`className`	`string`	`''`	Additional CSS classes

CardImage Props

Prop	Type	Default	Description
`src`	`string`	required	Image source URL
`alt`	`string`	required	Accessible image description
`aspectRatio`	`string`	`'16/9'`	CSS aspect ratio for the image container
`className`	`string`	`''`	Additional CSS classes

CardGrid Props

Prop	Type	Default	Description
`columns`	`number`	`3`	Number of columns at the largest breakpoint
`gap`	`number`	`6`	Tailwind gap unit between cards
`children`	`ReactNode`	required	Card components to arrange
`className`	`string`	`''`	Additional CSS classes

Styling with Plain CSS

If you're not using Tailwind:

css example

/* Card.module.css */
.card {
  border-radius: 0.75rem;
  overflow: hidden;
  transition: all 0.2s ease;
}

.card-elevated {
  background: white;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
              0 2px 4px -2px rgba(0, 0, 0, 0.1);
  border: 1px solid #f3f4f6;
}

.card-elevated:hover {
  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1),
              0 4px 6px -4px rgba(0, 0, 0, 0.1);
}

.card-outlined {
  background: transparent;
  border: 2px solid #e5e7eb;
}

.card-outlined:hover {
  border-color: #60a5fa;
}

.card-filled {
  background: #f9fafb;
  border: 1px solid #e5e7eb;
}

.card-clickable {
  cursor: pointer;
  text-decoration: none;
  color: inherit;
}

.card-clickable:hover {
  transform: scale(1.02);
}

.card-clickable:active {
  transform: scale(0.98);
}

.card-grid {
  display: grid;
  gap: 1.5rem;
  grid-template-columns: 1fr;
}

@media (min-width: 768px) {
  .card-grid { grid-template-columns: repeat(2, 1fr); }
}

@media (min-width: 1024px) {
  .card-grid-3 { grid-template-columns: repeat(3, 1fr); }
  .card-grid-4 { grid-template-columns: repeat(4, 1fr); }
}

.card-header {
  padding: 1.5rem 1.5rem 0.5rem;
}

.card-body {
  padding: 1rem 1.5rem;
}

.card-footer {
  padding: 0.5rem 1.5rem 1.5rem;
  border-top: 1px solid #f3f4f6;
}

.card-image {
  width: 100%;
  aspect-ratio: 16/9;
  object-fit: cover;
}

Responsive Card Patterns

Here's a pattern for feature cards that stack on mobile and sit side-by-side on desktop:

jsx example

// Responsive card that stacks on mobile, side-by-side on desktop
export function FeatureCard({ icon, title, description, link }) {
  return (
    <Card variant="outlined" href={link}>
      <CardBody>
        <div className="flex flex-col sm:flex-row items-start gap-4">
          <span className="text-3xl" aria-hidden="true">{icon}</span>
          <div>
            <h3 className="text-lg font-semibold mb-2">{title}</h3>
            <p className="text-gray-600 dark:text-gray-400">{description}</p>
          </div>
        </div>
      </CardBody>
    </Card>
  );
}

Accessibility Notes

A few things to keep in mind:

Semantic structure — Cards render as <div> by default but switch to <a> when you pass href. The right element for the job.

Image alt text — CardImage requires an alt prop. Write something descriptive, or use an empty string for purely decorative images.

Focus indicators — Interactive cards should have visible focus styles. Add focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:outline-none for keyboard users.

External links — When href starts with http, the component adds target="_blank" and rel="noopener noreferrer" automatically.

Content hierarchy — Use proper heading levels inside cards. If your cards live under an <h2>, use <h3> for card titles.

Color contrast — Make sure text in all card variants meets WCAG AA (4.5:1 for normal text, 3:1 for large text).

Advanced: Animated Card Hover

Add a subtle gradient overlay on hover:

jsx example

export function AnimatedCard({ children, ...props }) {
  return (
    <Card
      {...props}
      className="group relative overflow-hidden"
    >
      {/* Gradient overlay on hover */}
      <div className="absolute inset-0 bg-gradient-to-r from-blue-500/0 to-purple-500/0 group-hover:from-blue-500/5 group-hover:to-purple-500/5 transition-all duration-300" />
      <div className="relative z-10">
        {children}
      </div>
    </Card>
  );
}

Summary

This Card system uses the compound component pattern — Card, CardHeader, CardBody, CardFooter, CardImage all work together but give you full control over structure. Mix and match the pieces, throw them in a grid, make them clickable. One component system, tons of layouts.

Why Cards in MDX?

Component Source Code

Here's the full Card system with sub-components for header, body, footer, image, and grid:

Example

Basic Card Usage in MDX

Here's a simple card with header, body, and footer:

mdx example

import { Card, CardHeader, CardBody, CardFooter } from '../components/Card';

# Feature Overview

<Card>
  <CardHeader>
    ## Getting Started
  </CardHeader>
  <CardBody>
    Learn how to set up your development environment and create
    your first MDX-powered application in under 5 minutes.
  </CardBody>
  <CardFooter>
    **Estimated time:** 5 minutes
  </CardFooter>
</Card>

Card with Image

Add a hero image at the top:

mdx example

import { Card, CardImage, CardBody } from '../components/Card';

<Card variant="elevated">
  <CardImage
    src="/images/tutorial-hero.jpg"
    alt="Screenshot of the completed tutorial project"
  />
  <CardBody>
    ## Complete Tutorial

    Build a full documentation site from scratch using MDX,
    Next.js, and Tailwind CSS.
  </CardBody>
</Card>

Card Grid Layout

CardGrid arranges cards into a responsive grid — stacks on mobile, fills columns on desktop:

mdx example

import { Card, CardBody, CardGrid } from '../components/Card';

# Our Features

<CardGrid columns={3}>
  <Card variant="outlined">
    <CardBody>
      ### ⚡ Fast
      Lightning-fast builds with incremental compilation
      and smart caching strategies.
    </CardBody>
  </Card>

  <Card variant="outlined">
    <CardBody>
      ### 🔐 Secure
      Built-in security best practices with automatic
      vulnerability scanning.
    </CardBody>
  </Card>

  <Card variant="outlined">
    <CardBody>
      ### 📱 Responsive
      Mobile-first design that looks great on every
      device and screen size.
    </CardBody>
  </Card>
</CardGrid>

Card Variants

Elevated Card (Default)

Uses box shadows for a "floating" look. Shadow deepens on hover:

mdx example

<Card variant="elevated">
  <CardBody>
    This card appears to float above the page with a subtle shadow
    that intensifies on hover.
  </CardBody>
</Card>

Outlined Card

Borders instead of shadows. Flatter, more minimal:

mdx example

<Card variant="outlined">
  <CardBody>
    This card has a visible border and transparent background.
    On hover, the border color transitions to blue.
  </CardBody>
</Card>

Filled Card

Subtle background color to stand out from the page:

mdx example

<Card variant="filled">
  <CardBody>
    This card has a light gray background that differentiates
    it from the surrounding content.
  </CardBody>
</Card>

Clickable Cards (Link Cards)

Pass href to make the whole card a link:

mdx example

<CardGrid columns={2}>
  <Card href="/docs/getting-started" variant="outlined">
    <CardBody>
      ### 📖 Documentation
      Full guides and API references for every feature.
    </CardBody>
  </Card>

  <Card href="https://github.com/example/repo" variant="outlined">
    <CardBody>
      ### 🐙 GitHub
      View source code, report issues, and contribute to the project.
    </CardBody>
  </Card>
</CardGrid>

Props API Documentation

Card Props

Prop	Type	Default	Description
`variant`	`'elevated' \	'outlined' \	'filled'`	`'elevated'`	Visual style of the card
`children`	`ReactNode`	required	Card content (use sub-components for structure)
`href`	`string`	`undefined`	Makes the entire card a link
`onClick`	`function`	`undefined`	Click handler for interactive cards
`as`	`ElementType`	`'div'`	HTML element to render as
`className`	`string`	`''`	Additional CSS classes

CardImage Props

Prop	Type	Default	Description
`src`	`string`	required	Image source URL
`alt`	`string`	required	Accessible image description
`aspectRatio`	`string`	`'16/9'`	CSS aspect ratio for the image container
`className`	`string`	`''`	Additional CSS classes

CardGrid Props

Prop	Type	Default	Description
`columns`	`number`	`3`	Number of columns at the largest breakpoint
`gap`	`number`	`6`	Tailwind gap unit between cards
`children`	`ReactNode`	required	Card components to arrange
`className`	`string`	`''`	Additional CSS classes

Styling with Plain CSS

If you're not using Tailwind:

css example

/* Card.module.css */
.card {
  border-radius: 0.75rem;
  overflow: hidden;
  transition: all 0.2s ease;
}

.card-elevated {
  background: white;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
              0 2px 4px -2px rgba(0, 0, 0, 0.1);
  border: 1px solid #f3f4f6;
}

.card-elevated:hover {
  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1),
              0 4px 6px -4px rgba(0, 0, 0, 0.1);
}

.card-outlined {
  background: transparent;
  border: 2px solid #e5e7eb;
}

.card-outlined:hover {
  border-color: #60a5fa;
}

.card-filled {
  background: #f9fafb;
  border: 1px solid #e5e7eb;
}

.card-clickable {
  cursor: pointer;
  text-decoration: none;
  color: inherit;
}

.card-clickable:hover {
  transform: scale(1.02);
}

.card-clickable:active {
  transform: scale(0.98);
}

.card-grid {
  display: grid;
  gap: 1.5rem;
  grid-template-columns: 1fr;
}

@media (min-width: 768px) {
  .card-grid { grid-template-columns: repeat(2, 1fr); }
}

@media (min-width: 1024px) {
  .card-grid-3 { grid-template-columns: repeat(3, 1fr); }
  .card-grid-4 { grid-template-columns: repeat(4, 1fr); }
}

.card-header {
  padding: 1.5rem 1.5rem 0.5rem;
}

.card-body {
  padding: 1rem 1.5rem;
}

.card-footer {
  padding: 0.5rem 1.5rem 1.5rem;
  border-top: 1px solid #f3f4f6;
}

.card-image {
  width: 100%;
  aspect-ratio: 16/9;
  object-fit: cover;
}

Responsive Card Patterns

Here's a pattern for feature cards that stack on mobile and sit side-by-side on desktop:

jsx example

// Responsive card that stacks on mobile, side-by-side on desktop
export function FeatureCard({ icon, title, description, link }) {
  return (
    <Card variant="outlined" href={link}>
      <CardBody>
        <div className="flex flex-col sm:flex-row items-start gap-4">
          <span className="text-3xl" aria-hidden="true">{icon}</span>
          <div>
            <h3 className="text-lg font-semibold mb-2">{title}</h3>
            <p className="text-gray-600 dark:text-gray-400">{description}</p>
          </div>
        </div>
      </CardBody>
    </Card>
  );
}

Accessibility Notes

A few things to keep in mind:

Semantic structure — Cards render as <div> by default but switch to <a> when you pass href. The right element for the job.

Image alt text — CardImage requires an alt prop. Write something descriptive, or use an empty string for purely decorative images.

Focus indicators — Interactive cards should have visible focus styles. Add focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:outline-none for keyboard users.

External links — When href starts with http, the component adds target="_blank" and rel="noopener noreferrer" automatically.

Content hierarchy — Use proper heading levels inside cards. If your cards live under an <h2>, use <h3> for card titles.

Color contrast — Make sure text in all card variants meets WCAG AA (4.5:1 for normal text, 3:1 for large text).

Advanced: Animated Card Hover

Add a subtle gradient overlay on hover:

jsx example

export function AnimatedCard({ children, ...props }) {
  return (
    <Card
      {...props}
      className="group relative overflow-hidden"
    >
      {/* Gradient overlay on hover */}
      <div className="absolute inset-0 bg-gradient-to-r from-blue-500/0 to-purple-500/0 group-hover:from-blue-500/5 group-hover:to-purple-500/5 transition-all duration-300" />
      <div className="relative z-10">
        {children}
      </div>
    </Card>
  );
}