useThemeToggle

useThemeToggle() provides the state used by UIThemeToggle from @meekojs/ui. You can build a selector that preserves the SSR theme during hydration.

Usage#

Enable theme: true in meeko.config.ts and call the composable in a component's script:

import { useThemeToggle } from '@meekojs/meeko/framework'

const toggle = useThemeToggle()

Type#

function useThemeToggle(): ThemeToggleState

interface ThemeToggleState<
  Name extends string = ThemeName,
  Choice extends string = ThemeChoice,
> {
  readonly theme: ThemeState<Name, Choice>;
  readonly choices: readonly Choice[];
  readonly system: ThemeToggleSystem<Name> | undefined;
  readonly known: ReadonlySignal<boolean>;
  readonly interactive: ReadonlySignal<boolean>;
}

interface ThemeToggleSystem<Name extends string = ThemeName> {
	readonly light: Name
	readonly dark: Name
}

Parameters#

It takes no parameters. It reads the themes from the framework configuration.

Return value#

A ThemeToggleState<Name, Choice>, with names inferred from the configuration:

Examples#

import { computed } from '@meekojs/meeko'
import { useThemeToggle } from '@meekojs/meeko/framework'

const toggle = useThemeToggle()
const label = computed(() => (toggle.known.value ? `Theme: ${toggle.theme.theme.value}` : 'Cambiar tema'))

The custom theme selector includes a complete form with POST /_meeko/theme, theme and return, which switches through theme.set(choice) when interactive.value is true.

To avoid icon jumps, render all icons with data-meeko-theme-icon and let the <head> rule show the one for the choice. While known.value is false, announce a neutral action (“Change theme”).

Common mistakes#

Call it without configuring the theme#

// meeko.config.ts no activa theme
const toggle = useThemeToggle()

// meeko.config.ts
export default defineMeekoConfig({ theme: true })

Without theme in meeko.config.ts, or outside a Meeko application, it throws MEEK111. Enable theme: true and call it while a component's script is running.

Change the theme during SSR#

const toggle = useThemeToggle()
toggle.theme.set('dark') // setup also runs on the server

import { useThemeToggle } from '@meekojs/meeko/framework'

const toggle = useThemeToggle()
const chooseDark = (): void => {
	if (toggle.interactive.value) toggle.theme.set('dark')
}

theme.set() only changes the theme in the browser. In SSR, use the read-only state and preserve native form submission; do not call set during setup.

Notes#

• known and interactive are read-only signals: read .value in the binding that uses them.
• The form works without JavaScript with a server adapter. The static adapter requires JavaScript.
• The cookie, script, <head> icon rule and POST /_meeko/theme remain in core; they do not require UI.
• <MeekoThemeToggle> is deprecated since 1.8 and will be removed in 2.0. For a ready-made selector, enable the UI module and use <UIThemeToggle>.

Related#

• useThemeReturns the application's light/dark theme (choice, effective theme and theme list) and changes it in html, the cookie and other tabs.
• themeFlicker-free light, dark or custom application themes, with the choice in a cookie, the theme on html from the first byte and useTheme in components.
• Custom theme selectorMeeko as a full-stack framework