# How Astryx ThemeProvider Handles Dark Mode Switching and CSS Custom Property Overrides > Discover how Astryx ThemeProvider manages dark mode switching and CSS custom property overrides with data-theme attributes and layered @scope rules for seamless theming. - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: deep-dive - Published: 2026-08-04 --- **Astryx's `Theme` provider synchronizes browser color-schemes via `data-theme` attributes on the `` element while injecting scoped CSS custom properties through layered `@scope` rules that respect both nested themes and portal-rendered content.** The `Theme` component in `facebook/astryx` serves as the central hub for design-system theming, combining StyleX-based styling with runtime CSS injection to enable seamless dark mode transitions and token customization without rebuilds. ## Dark Mode Handling in Theme.tsx ### Mode Prop and Color-Scheme Styles The `Theme` component accepts a `mode` prop typed as `'light' | 'dark' | 'system'`, defaulting to `'system'` to respect OS-level preferences. In [`packages/core/src/theme/Theme.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/Theme.tsx) at lines 56-58, this prop determines which color-scheme wrapper style gets applied. ```tsx // Theme.tsx lines 71-79 const wrapperStyles = stylex.create({ light: { colorScheme: 'light' }, dark: { colorScheme: 'dark' }, system: { colorScheme: 'light dark' }, }); ``` ### Root-Level Synchronization with useRootThemeSync The first (non-nested) `Theme` instance executes `useRootThemeSync`, which performs two critical DOM operations according to [`Theme.tsx`](https://github.com/facebook/astryx/blob/main/Theme.tsx) lines 80-95: - Writes `data-theme="light"` or `data-theme="dark"` on the `` element — consumed by [`reset.css`](https://github.com/facebook/astryx/blob/main/reset.css) to set native browser UI colors - Removes the attribute entirely in `'system'` mode, falling back to `color-scheme: light dark` - Adds `data-astryx-theme=""` for **@scope**-based CSS targeting of portals and external elements ### Nested Theme Detection Secondary `Theme` components create a `ThemeNestingContext` (`React.createContext(false)`). When `isNested` is detected at lines 86-94, the root-sync hook is skipped entirely. This prevents duplicate attribute writes while preserving per-theme styling through scoped CSS injection. ## CSS Custom Property Overrides ### Token Definition with defineTheme.ts Themes are constructed via `defineTheme` in [`packages/core/src/theme/defineTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/defineTheme.ts). The `tokens` field accepts two value shapes per [`defineTheme.ts`](https://github.com/facebook/astryx/blob/main/defineTheme.ts) lines 55-59: - **Static strings**: Applied universally across modes - **`[light, dark]` tuples**: Compile-time conversion to CSS `light-dark()` functions ```tsx // defineTheme.ts usage pattern const theme = defineTheme({ name: 'ocean', tokens: { '--color-background': ['#f0f8ff', '#001726'], // tuple → light-dark() '--color-text-primary': '#111', // static }, }); ``` ### Runtime Style Injection via useThemeStyleInjection For unbuilt themes, `useThemeStyleInjection` ([`Theme.tsx`](https://github.com/facebook/astryx/blob/main/Theme.tsx) lines 101-158) generates dual `