Skip to content
Astro Eclipse
Esc
↑↓navigate↵open⌘Jpreview
On this page

Framework islands

A useTheme hook for React, Vue, Svelte and Solid built on getTheme and onThemeChange.

The client API is plain TypeScript, so it works inside any island. What an island usually needs is the current theme as reactive state, to render a different icon or label. onThemeChange and getTheme are enough to build that.

These hooks are examples to copy into your project, not packages. Each one:

  • reads the theme on the client only;
  • unsubscribes when the component goes away;
  • returns the applied theme (light, dark, never system) and the visitor’s preference (which may be system).

To change the theme, call toggleTheme or setTheme from the event handler in the island as usual.

React

import { useSyncExternalStore } from 'react'
import { getPreference, getTheme, onThemeChange } from 'astro-eclipse/client'

const subscribe = (notify: () => void) => onThemeChange(() => notify())

export function useTheme() {
  // The server snapshot must match the server-rendered HTML, so it cannot read the visitor's real theme.
  const theme = useSyncExternalStore(subscribe, getTheme, () => undefined)
  const preference = useSyncExternalStore(subscribe, getPreference, () => undefined)
  return { theme, preference }
}
import { toggleTheme } from 'astro-eclipse/client'
import { useTheme } from '../hooks/useTheme'

export function ThemeButton() {
  const { theme } = useTheme()
  return (
    <button type="button" onClick={(event) => toggleTheme({ origin: event.nativeEvent })}>
      {theme === 'dark' ? 'Switch to light' : 'Switch to dark'}
    </button>
  )
}

event.nativeEvent is the DOM MouseEvent that origin expects.

On the server and during hydration the hook returns undefined, so the first render matches the server HTML and React reports no mismatch. The real theme arrives right after hydration. Render the island with client:only="react" to skip the server render entirely.

Vue

import { onMounted, onUnmounted, readonly, ref } from 'vue'
import { getPreference, getTheme, onThemeChange } from 'astro-eclipse/client'

export function useTheme() {
  const theme = ref<string>()
  const preference = ref<string>()
  let stop: (() => void) | undefined

  const sync = () => {
    theme.value = getTheme()
    preference.value = getPreference()
  }

  onMounted(() => {
    sync()
    stop = onThemeChange(sync)
  })
  onUnmounted(() => stop?.())

  return { theme: readonly(theme), preference: readonly(preference) }
}

Both values are undefined until the component mounts, so the server render and the first client render agree.

Svelte

Svelte 5, in a .svelte.ts file so runes work:

import { onMount } from 'svelte'
import { getPreference, getTheme, onThemeChange } from 'astro-eclipse/client'

export function useTheme() {
  let theme = $state<string>()
  let preference = $state<string>()

  onMount(() => {
    const sync = () => {
      theme = getTheme()
      preference = getPreference()
    }
    sync()
    return onThemeChange(sync)
  })

  return {
    get theme() {
      return theme
    },
    get preference() {
      return preference
    },
  }
}

The function returned from onMount runs when the component is destroyed, which unsubscribes.

Solid

import { createSignal, onCleanup, onMount } from 'solid-js'
import { getPreference, getTheme, onThemeChange } from 'astro-eclipse/client'

export function useTheme() {
  const [theme, setCurrentTheme] = createSignal<string>()
  const [preference, setCurrentPreference] = createSignal<string>()

  onMount(() => {
    const sync = () => {
      setCurrentTheme(getTheme())
      setCurrentPreference(getPreference())
    }
    sync()
    onCleanup(onThemeChange(sync))
  })

  return { theme, preference }
}

Read the values by calling them: theme().

Without a hook

onThemeChange is a thin wrapper over a DOM event. Anything that can listen to document can use it directly:

document.addEventListener('eclipse:change', (event) => {
  const { theme, preference } = (event as CustomEvent<{ theme: string; preference: string }>).detail
})

The event is fired by the head script as well, so it also covers changes from the system setting and from other tabs.

Related: client API, ClientRouter.

Was this page helpful?