Dark mode

Introduction

The Dark mode component provides a toggle for switching between light and dark color schemes. It uses system preferences, persists user choices, and follows accessibility best practices.

When to use

• Website theming
• User interface customization
• Reducing eye strain in low-light conditions
• Respecting user system preferences
• Battery saving on OLED displays

Quick example

Click the toggle below to switch between light and dark mode:

Try using keyboard navigation (Tab + Enter/Space) to toggle!

Example component

The toggle here doesn’t change the color scheme (just for itself) since Starlight has its own dark mode toggle and doesn’t use the darkmode class.

Usage

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

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

<!-- Default with system preference -->
<DarkMode />

<!-- With custom icons -->
<DarkMode>
  <Icon name="ion:bulb" slot="light" />
  <Icon name="ion:bulb-outline" slot="dark" />
</DarkMode>

Initial mode

Use the initialMode prop to set the default color scheme. Options are ‘light’, ‘dark’, or ‘auto’ (uses system preference).

Class .darkmode

The component sets a class of darkmode on the html element when dark mode is active. You can use this class to apply styles to your website.

Props

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

Prop	Type	Default	Description
initialMode	'light' | 'dark' | 'auto'	'auto'	Sets the initial color scheme mode
label	string	'Toggle Dark Mode'	Accessible label for the toggle button
class	string	''	Additional CSS classes to apply

Slots

The DarkMode component supports named slots for customizing the icons displayed in light and dark modes.

Slot	Description
light	Icon or content to display when in light mode
dark	Icon or content to display when in dark mode

Accessibility

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

• Uses semantic button element
• Proper ARIA attributes (aria-pressed, aria-label)
• Maintains focus states
• Persists across page loads using localStorage

Styling

Make the DarkMode 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(.darkmode-toggle) {
    font-size: 1.125rem;
    color: light-dark(hsl(215 8% 45%), hsl(215 8% 65%));
  }

  :global(.darkmode-toggle:hover) {
    color: light-dark(hsl(215 25% 27%), hsl(215 25% 89%));
  }

  /* Dark mode styles applied to html element */
  :global(.darkmode) {
    color-scheme: dark;
    background: hsl(0 0% 10%);
    color: hsl(0 0% 100%);
  }
</style>

/* Option 2: Using is:global on the style tag */
<style is:global>
  .darkmode-toggle {
    font-size: 1.125rem;
    color: light-dark(hsl(215 8% 45%), hsl(215 8% 65%));
  }

  .darkmode-toggle:hover {
    color: light-dark(hsl(215 25% 27%), hsl(215 25% 89%));
  }

  /* Dark mode styles applied to html element */
  .darkmode {
    color-scheme: dark;
    background: hsl(0 0% 10%);
    color: hsl(0 0% 100%);
  }
</style>

Tailwind Classes

<DarkMode
  class="text-lg text-gray-600 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100"
>
  <Icon
    name="ion:sunny"
    slot="light"
    class="w-6 h-6"
  />
  <Icon
    name="ion:moon"
    slot="dark"
    class="w-6 h-6"
  />
</DarkMode>

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 DarkMode component in action with these practical examples demonstrating different variants and styling options.

Example component

The toggle here doesn’t change the color scheme (just for itself) since Starlight has its own dark mode toggle and doesn’t use the darkmode class.

Default style

With custom icons