Function resolveThemePreference

resolveThemePreference(storageKey: string): PreferenceResult<ResolvedTheme>

Resolve the current website theme.

Resolution checks the URL query named by storageKey, local storage under the same key, the current prefers-color-scheme media query, and finally the fixed light fallback. Query values accept only light and dark. Storage also accepts system, which resolves to a concrete value while retaining the System label. URL query preferences apply only to the current resolution and are not persisted.

Resolution matrix:

Query	Storage	System dark	Result
`dark`	`light`	false	`{ value: "dark", label: "Dark" }`
`light`	`dark`	true	`{ value: "light", label: "Light" }`
invalid	`dark`	false	`{ value: "dark", label: "Dark" }`
missing	`light`	true	`{ value: "light", label: "Light" }`
missing	`system`	true	`{ value: "dark", label: "System" }`
missing	`system`	false	`{ value: "light", label: "System" }`
missing	invalid	true	`{ value: "dark", label: "System" }`
missing	missing	false	`{ value: "light", label: "System" }`
missing	missing	unavailable	`{ value: "light", label: "Light" }`

Usage:

import {
  resolveThemePreference,
  setThemePreference,
} from "mazey";

const theme = resolveThemePreference(
  "MY_WEBSITE_THEME"
);

console.log(theme);

setThemePreference(
  "MY_WEBSITE_THEME",
  "system"
);

Possible output:

{
  value: "dark",
  label: "System"
}

Parameters

storageKey: string
Project-specific URL query and local-storage key.

Returns PreferenceResult<ResolvedTheme>

The concrete light or dark value and the label of the preference that selected it.

Throws

If storageKey is not a non-empty string.

Remarks

Safe during SSR and resilient to unavailable or throwing browser APIs. Resolution is read-only: the function never writes storage, mutates the DOM, or adds listeners.