ThemedImage Component

Features

• ✅ Supports both light and dark mode images
• ✅ Uses Astro's optimized Image component for performance
• ✅ Supports the ~/images alias path
• ✅ Automatic image optimization and processing
• ✅ TypeScript support with strict typing
• ✅ Follows Starlight's theming conventions (light:sl-hidden and dark:sl-block)

Live Demo

Try switching between light and dark mode to see the component in action:

Usage

Basic Usage

---
import ThemedImage from '~/components/ThemedImage';
---

<ThemedImage
  alt="Staking Flow"
  sources={{
    light: '~/images/staking-light.svg',
    dark: '~/images/staking-dark.svg',
  }}
/>

With Custom Dimensions

<ThemedImage
  alt="Aptos Token Standard Flow"
  sources={{
    light: '~/images/aptos-token-standard-flow.svg',
    dark: '~/images/aptos-token-standard-flow-dark.svg',
  }}
  width={600}
  height={400}
/>

With Custom CSS Class

<ThemedImage
  alt="Digital Asset"
  sources={{
    light: '~/images/digital-asset-light.svg',
    dark: '~/images/digital-asset-dark.svg',
  }}
  class="rounded-lg shadow-md"
/>

Using Imported Images

---
import lightImage from '~/images/my-light-image.png';
import darkImage from '~/images/my-dark-image.png';
import ThemedImage from '~/components/ThemedImage';
---

<ThemedImage
  alt="My Image"
  sources={{
    light: lightImage,
    dark: darkImage,
  }}
/>

Props

| Prop | Type | Required | Default | Description | | ---------- | ------------------------------------------------------------------- | -------- | --------- | --------------------------------------------------- | | alt | string | ✅ | - | Alt text for the image (required for accessibility) | | sources | { light: string \| ImageMetadata, dark: string \| ImageMetadata } | ✅ | - | Object containing light and dark mode image sources | | width | number | ❌ | - | Image width in pixels | | height | number | ❌ | - | Image height in pixels | | loading | 'lazy' \| 'eager' | ❌ | 'lazy' | Image loading strategy | | decoding | 'async' \| 'sync' \| 'auto' | ❌ | 'async' | Image decoding strategy | | class | string | ❌ | '' | Additional CSS classes to apply |

How It Works

The component renders two <Image> components:

1. Light mode image: Visible in light theme, hidden in dark theme (light:sl-block dark:sl-hidden)
2. Dark mode image: Hidden in light theme, visible in dark theme (light:sl-hidden dark:sl-block)

Both images use Astro's optimized <Image> component, which provides:

• Automatic image optimization
• WebP/AVIF format conversion
• Responsive image generation
• Lazy loading by default
• Cumulative Layout Shift (CLS) prevention

Image Path Aliases

The component supports the ~/images alias configured in your Astro project:

astro.config.mjs

export default defineConfig({
  vite: {
    resolve: {
      alias: {
        "~/images": fileURLToPath(new URL("./src/assets/images", import.meta.url)),
      },
    },
  },
});

This allows you to use paths like ~/images/my-image.svg instead of relative paths.

CSS Classes

The component uses Starlight's theming classes:

• light:sl-block - Shows element in light mode
• dark:sl-hidden - Hides element in dark mode
• light:sl-hidden - Hides element in light mode
• dark:sl-block - Shows element in dark mode

More Examples

Here are additional examples showing different use cases: