Card

Introduction

The Card component provides a versatile container for displaying related content. It uses semantic HTML and ensures proper heading structure and content organization. The component includes built-in support for Astro’s Image component, enabling optimized image loading and better performance out of the box.

When to use

• Featured content sections
• Product displays
• Blog post previews
• Service highlights
• Team member profiles
• Any grouped content that benefits from visual containment

Quick example

Accessible Card

This card component maintains proper heading structure and includes keyboard focus styles.

Try hovering and focusing on this card

Versatile Design

Cards can be used for various content types and adapt to different layouts.

Click to navigate (opens in same tab)

Image optimization

The Card component supports Astro’s built-in Image component for automatic image optimization, responsive images, and improved Core Web Vitals. See the “With Astro Image component” example for implementation details.

Usage

Learn how to implement the Card component in your project, from basic usage to advanced configurations.

Basic

---
import { Card } from 'accessible-astro-components'
---

<Card
  img="path/to/image.jpg"
  url="/blog/post"
  title="Card Title"
>
  <p>This is the card content that can include any HTML.</p>
</Card>

With meta info

---
import { Card } from 'accessible-astro-components'
---

<Card
  img="path/to/image.jpg"
  url="/blog/post"
  title="Card Title"
  footer="Card footer content"
>
  <span slot="meta">
    <Badge text="Science" variant="tip" />
    <Badge text="Technology" variant="danger" />
  </span>
  <p>This is the card content that can include any HTML.</p>
</Card>

With Astro Image component

---
import { Card } from 'accessible-astro-components'
import localImage from '../assets/local-image.jpg'
---

<!-- Using local image -->
<Card
  imageComponent={localImage}
  url="/blog/post"
  title="Card with Local Image"
>
  <p>This card uses Astro's Image component with a local image.</p>
</Card>

<!-- Using remote image with dynamic import -->
<Card
  imageComponent={(await import('https://example.com/remote-image.jpg')).default}
  width={800}
  height={600}
  url="/blog/post"
  title="Card with Remote Image"
>
  <p>This card uses Astro's Image component with a remote image.</p>
</Card>

Flexible content

The Card component accepts any content through its default slot, allowing for flexible layouts while maintaining accessibility. You can use the meta slot to add additional information to the card.

Props

Configure the Card component using these available props to customize its behavior and appearance.

Prop	Type	Default	Description
url	string	'#'	URL for the card’s link wrapper
img	string	'https://fakeimg.pl/640x360'	Path to the card’s image
imageComponent	ImageMetadata | Promise<{ default: ImageMetadata }>	undefined	Optional Astro Image component (supports both ImageMetadata and dynamic import)
imageAlt	string	''	Alt text for the image
width	number	640	Width of the image (required for remote images)
height	number	360	Height of the image (required for remote images)
inferSize	boolean	false	Whether to infer the image size (for remote images)
title	string	'Default title'	Title text for the card
class	string	''	Additional CSS classes to apply to the card
tagName	string	'h3'	HTML tag name for the title
footer	string	''	Footer content for the card

Accessibility

Accessibility isn’t an afterthought - it’s built into the core of this component through semantic HTML elements and proper image handling. The Card component is built with accessibility in mind:

• Uses semantic HTML structure with <article> element
• Proper heading hierarchy with configurable levels (via tagName prop)
• Images have appropriate alt text support (via imageAlt prop)
  • Empty alt text (alt="") is appropriate when the image is decorative and the key content is conveyed through title and description
  • Add meaningful alt text for informative images that aren’t described elsewhere in the card
• Links are properly structured for keyboard navigation with clear focus states
• Images have appropriate width and height attributes to prevent layout shifts
• Works with Astro’s Image component for optimal loading and performance
• Color contrast meets WCAG guidelines

Styling

Make the Card component your own with custom styling while maintaining its accessibility features.

Accessibility considerations

When applying custom styles, ensure they don’t compromise accessibility by maintaining sufficient color contrast and touch target sizes.

Custom CSS

/* Option 1: Using :global() in your style block */
<style>
  :global(.card) {
    border-radius: 0.5rem;
    overflow: hidden;
    background: light-dark(hsl(204 20% 94%), hsl(215 25% 15%));
    color: light-dark(hsl(215 25% 27%), hsl(215 25% 89%));
  }

  :global(.card:hover) {
    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  }

  :global(.card__image) {
    aspect-ratio: 16/9;
    object-fit: cover;
  }

  :global(.card__content) {
    padding: 1rem;
  }

  :global(.card__title) {
    margin-block-start: 0;
    font-size: 1.25rem;
  }
</style>

/* Option 2: Using is:global on the style tag */
<style is:global>
  .card {
    border-radius: 0.5rem;
    overflow: hidden;
    background: light-dark(hsl(204 20% 94%), hsl(215 25% 15%));
    color: light-dark(hsl(215 25% 27%), hsl(215 25% 89%));
  }

  .card:hover {
    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  }

  .card__image {
    aspect-ratio: 16/9;
    object-fit: cover;
  }

  .card__content {
    padding: 1rem;
  }

  .card__title {
    margin-block-start: 0;
    font-size: 1.25rem;
  }
</style>

Tailwind Classes

<Card
  class="rounded-lg overflow-hidden bg-white dark:bg-gray-800 hover:shadow-md"
  title="Example Card"
  url="#"
  img="path/to/image.jpg"
>
  <p class="text-gray-600 dark:text-gray-300">
    Card content with Tailwind styling
  </p>
</Card>

Style scoping

Astro components use scoped styles by default. To override component styles, you’ll need to use either :global() selectors or the is:global directive on your style tag.

Interactive example

See the Card component in action with this example demonstrating different variants and styling options.

Default style

Example card

This is an example of the Card component with an image, title, and custom content that demonstrates how the component handles different types of content while maintaining accessibility and visual appeal.

With meta info

Example card

ScienceTechnology

This is an example of the Card component with an image, title, and custom content that shows how to use meta tags through the meta slot. The badges in the meta slot can be used to categorize or tag the card content.