Function resolveThemePreference

resolveThemePreference(storageKey: string): PreferenceResult<ResolvedTheme>

Resolve the current website theme.

Resolution checks the fixed theme URL query, the supplied local-storage 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. A valid query preference is written under the supplied storage key when browser storage is available; resolution still succeeds when the write fails.

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 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. A valid URL preference is written to storage when possible; other resolution paths remain read-only. The function never mutates the DOM or adds listeners.