useTheme

<script setup lang="ts">
import MtThemeSelect from "@shopware-ag/meteor-component-library/MtThemeSelect";
import MtText from "@shopware-ag/meteor-component-library/MtText";
// useTheme has no subpath export, so it is imported from the barrel.
import { useTheme } from "@shopware-ag/meteor-component-library";

// Persistence and global application are disabled so the docs page itself
// stays untouched. Omit these options in your app.
const { theme, resolvedTheme } = useTheme({
  storageKey: null,
  applyToTarget: false,
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <mt-theme-select v-model="theme" label="Color theme" />

    <mt-text>Resolved theme: {{ resolvedTheme }}</mt-text>
  </div>
</template>

Usage

useTheme manages the application color theme. It tracks the user's preference (light, dark, or system), resolves system against the operating system via prefers-color-scheme, writes the resolved value to a target element's data-theme attribute (the document root by default), and persists the choice to localStorage. Bind the returned theme ref to Theme Select with v-model to let users control it.

import { useTheme } from "@shopware-ag/meteor-component-library";

const { theme, resolvedTheme, setTheme, stop } = useTheme();

The preference is shared: instances using the same storageKey stay in sync within the document and across browser tabs.

API

Options

useTheme(options?) accepts:

Option	Type	Description
`storageKey`	`string \| null`	The `localStorage` key used to persist the preference. Defaults to `"mt-theme"`. Set it to `null` to disable persistence.
`target`	`HTMLElement`	The element whose `data-theme` attribute is kept in sync with the resolved theme. Defaults to `document.documentElement`.
`defaultTheme`	`"light" \| "dark" \| "system"`	The preference used when nothing has been persisted yet. Defaults to `"system"`.
`applyToTarget`	`boolean`	Whether to write the resolved theme to the target's `data-theme` attribute. Defaults to `true`. Disable it when the host applies the theme itself.

Return value

Member	Type	Description
`theme`	`Ref<Theme>`	The user's preference: `"light"`, `"dark"`, or `"system"`. Writable; bind it to Theme Select with `v-model`.
`resolvedTheme`	`ComputedRef<ResolvedTheme>`	The applied theme after resolving `"system"`: `"light"` or `"dark"`.
`setTheme`	`(theme: Theme) => void`	Sets the preference programmatically.
`stop`	`() => void`	Releases all listeners. Called automatically on scope disposal when used inside a component or `effectScope`; call it manually when using the composable outside of an active scope.

Types

type Theme = "light" | "dark" | "system";
type ResolvedTheme = "light" | "dark";

Behavior

While the preference is system, resolvedTheme updates live when the operating system preference changes.
Invalid persisted values are ignored and fall back to defaultTheme.
Meteor tokens are theme-aware through data-theme, so applying the resolved theme to the document root themes every Meteor component on the page.

Theme Select: the select component built for choosing the theme this composable manages.

Edit this pageorReport an issue

useSnackbar

A composable for publishing snackbar notifications from anywhere in your app.

Tooltip

A v-tooltip directive for attaching a tooltip to any element, a lightweight alternative to the Tooltip component.