Media

Introduction

The Media component provides a flexible way to display images with built-in support for different aspect ratios and loading strategies. It uses semantic HTML and follows best practices for performance and accessibility.

Astro's Image component

Astro provides a powerful Image component with excellent image optimization capabilities. Our Media component complements Astro’s ecosystem as part of our accessibility-focused component collection, offering ready-to-use defaults and aspect ratio handling that integrates seamlessly with other accessible-astro-components.

When to use

The Media component is perfect for situations where you need responsive images with controlled aspect ratios:

• Hero images
• Product galleries
• Blog post featured images
• Profile pictures
• Background images
• Above-the-fold content
• Image-heavy layouts

Quick example

This image maintains its aspect ratio across all screen sizes and loads with optimal performance.

Usage

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

Basic

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

<Media
  src="/path/to/image.jpg"
  alt="Descriptive alt text"
  ratio="16:9"
/>

Loading strategy

Use the loading and fetchpriority props to optimize the loading behavior of above-the-fold images.

With custom loading

<Media
  src="/hero-image.jpg"
  alt="Hero section image"
  ratio="21:9"
  loading="eager"
  fetchpriority="high"
/>

Props

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

Prop	Type	Default	Description
src	string	'https://fakeimg.pl/640x360'	URL or path to the image
alt	string	''	Alternative text for the image
ratio	'1:1' | '4:3' | '16:9' | '21:9' | 'auto'	'auto'	Aspect ratio of the image
loading	'lazy' | 'eager'	'lazy'	Image loading strategy
decoding	'async' | 'sync' | 'auto'	'async'	Image decoding behavior
fetchpriority	'high' | 'low' | 'auto'	'auto'	Resource loading priority
class	string	''	Additional CSS classes to apply

Accessibility

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

• Required alt text support
• Maintains aspect ratio without layout shift
• Proper loading states
• Respects user’s reduced data preferences
• Semantic HTML structure

Styling

Make the Media 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 proper image visibility and loading states.

Custom CSS

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

  :global(.media img) {
    width: 100%;
    height: 100%;
    object-fit: cover;
    transition: transform 0.2s ease;
  }

  :global(.media:hover img) {
    transform: scale(1.05);
  }

  :global(.media[data-loading="true"])::before {
    content: '';
    position: absolute;
    inset: 0;
    background: light-dark(hsl(204 10% 90% / 0.5), hsl(215 15% 15% / 0.5));
  }
</style>

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

  .media img {
    width: 100%;
    height: 100%;
    object-fit: cover;
    transition: transform 0.2s ease;
  }

  .media:hover img {
    transform: scale(1.05);
  }

  .media[data-loading="true"]::before {
    content: '';
    position: absolute;
    inset: 0;
    background: light-dark(hsl(204 10% 90% / 0.5), hsl(215 15% 15% / 0.5));
  }
</style>

Tailwind Classes

<Media
  src="/image.jpg"
  alt="Example image"
  class="rounded-lg overflow-hidden bg-gray-100 dark:bg-gray-800 hover:scale-105 transition-transform duration-200"
/>

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 examples

See the Media component in action with these practical examples demonstrating different aspect ratios and use cases.

Default style

Square aspect ratio

Widescreen format