Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(useTheme): a mode outside light|dark|system resolves like system (#9254)

Cindy Zhang6127f4d0d7cd
diff --git a/.changeset/use-theme-mode-out-of-range.md b/.changeset/use-theme-mode-out-of-range.md
new file mode 100644
index 0000000000..c6372e97d3
--- /dev/null
+++ b/.changeset/use-theme-mode-out-of-range.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] useTheme: `mode` is always `'light'` or `'dark'`. A mode outside `light | dark | system`, such as a stale persisted preference, now resolves through the OS preference like `'system'` instead of being returned as is. First fixed in #5617.
+
+@cixzhang @AKnassa
diff --git a/packages/core/src/theme/useTheme.test.tsx b/packages/core/src/theme/useTheme.test.tsx
index fc48c465ec..c528b0370b 100644
--- a/packages/core/src/theme/useTheme.test.tsx
+++ b/packages/core/src/theme/useTheme.test.tsx
@@ -7,6 +7,7 @@ import {Theme} from './Theme';
import {defineTheme} from './defineTheme';
import {resetThemes} from './themeRegistry';
import {useTheme} from './useTheme';
+import {useMediaQuery} from '../hooks/useMediaQuery';
import {resolveThemeTokens} from './tokens';
// Mock useMediaQuery — default to light mode
@@ -132,6 +133,32 @@ describe('useTheme', () => {
expect(result.current.mode).toBe('dark');
});
+ describe('modes outside light|dark|system', () => {
+ // A persisted preference read back untyped can hand Theme a stale
+ // string. It resolves like system, through the OS preference, never
+ // as the string itself.
+ afterEach(() => {
+ vi.mocked(useMediaQuery).mockReturnValue(false);
+ });
+
+ it.each([
+ ['banana', false, 'light'],
+ ['DARK', false, 'light'],
+ ['', false, 'light'],
+ ['banana', true, 'dark'],
+ ] as const)(
+ 'resolves "%s" like system (prefersDark=%s -> %s)',
+ (value, prefersDark, expected) => {
+ vi.mocked(useMediaQuery).mockReturnValue(prefersDark);
+ const {result} = renderHook(() => useTheme(), {
+ wrapper: ({children}) =>
+ wrapper({children, mode: value as 'light' | 'dark' | 'system'}),
+ });
+ expect(result.current.mode).toBe(expected);
+ },
+ );
+ });
+
it('provides a tokens map with all resolved values', () => {
const {result} = renderHook(() => useTheme(), {
wrapper: ({children}) => wrapper({children, mode: 'light'}),
diff --git a/packages/core/src/theme/useTheme.ts b/packages/core/src/theme/useTheme.ts
index a260f20ccf..3c3b58e8a3 100644
--- a/packages/core/src/theme/useTheme.ts
+++ b/packages/core/src/theme/useTheme.ts
@@ -10,6 +10,8 @@
*
* Provides synchronous access to theme token values resolved for the
* current color mode — no DOM reads on the provider path, no double render.
+ * The returned `mode` is always 'light' | 'dark': 'system', and any value
+ * outside the union, resolves through the OS preference.
* Without a reachable ThemeContext it consults `<html data-theme>` and
* `<html data-astryx-theme>` (kept in sync by Theme) via shared, refcounted
* MutationObservers before assuming OS preference/default tokens. Provider-path
@@ -296,8 +298,11 @@ export function useTheme(): UseThemeReturn {
const mode = ctx?.mode ?? rootAttrMode ?? 'system';
const theme = ctx?.theme ?? getRegisteredTheme(rootThemeName);
+ // Anything outside light|dark (a stale persisted preference cast to
+ // ThemeMode, say) resolves like 'system', the way the root Theme's <html>
+ // sync already treats it, so the declared return type holds.
const effectiveMode: 'light' | 'dark' =
- mode === 'system' ? (prefersDark ? 'dark' : 'light') : mode;
+ mode === 'light' || mode === 'dark' ? mode : prefersDark ? 'dark' : 'light';
// Build the full resolved map, memoized on theme + effective mode
const tokens = useMemo(