> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme Switching

> Enable users to switch between theme modes and custom themes in your Neo application using the built-in theme provider.

Neo provides built-in theme switching capabilities through the `neoCurrentThemeProvider`. You can switch between theme modes (light, dark, system) or switch to completely different custom themes.

## Understanding Modes vs Themes

**Theme Modes** control which theme to use:

* `light` - Always use the light theme
* `dark` - Always use the dark theme
* `system` - Automatically choose based on device settings

**Themes** are the actual theme objects:

* Default themes: `NeoThemeLight()`, `NeoThemeDark()`
* Custom themes: Your brand themes, seasonal themes, compact themes, etc.

## Example

<CodeGroup>
  ```dart Simple Mode Toggle lines theme={null}
  class ThemeToggle extends ConsumerWidget {
    @override
    Widget build(BuildContext context, WidgetRef ref) {
      final currentMode = ref.read(neoCurrentThemeProvider.notifier).getSelectedThemeMode();
      
      return NeoButton(
        label: currentMode == NeoThemeMode.light ? "Dark Mode" : "Light Mode",
        icon: currentMode == NeoThemeMode.light 
          ? PhosphorIconsRegular.moon 
          : PhosphorIconsRegular.sun,
        onPressed: () {
          final newMode = currentMode == NeoThemeMode.light 
            ? NeoThemeMode.dark 
            : NeoThemeMode.light;
            
          ref.read(neoCurrentThemeProvider.notifier).updateTheme(mode: newMode);
        },
      );
    }
  }
  ```
</CodeGroup>

## Theme Provider

<ParamField path="neoCurrentThemeProvider" type="StateNotifierProvider">
  Manages theme modes and custom themes throughout your application.
</ParamField>

### Provider Methods

<CodeGroup>
  ```dart Update Theme Mode lines theme={null}
  // Switch to a specific mode
  ref.read(neoCurrentThemeProvider.notifier).updateTheme(mode: NeoThemeMode.dark);

  // Switch to system mode
  ref.read(neoCurrentThemeProvider.notifier).updateTheme(mode: NeoThemeMode.system);
  ```

  ```dart Update Custom Themes lines theme={null}
  // Switch to custom themes
  ref.read(neoCurrentThemeProvider.notifier).updateTheme(
    lightTheme: MyCustomThemeLight(),
    darkTheme: MyCustomThemeDark(),
  );

  // Update mode and themes together
  ref.read(neoCurrentThemeProvider.notifier).updateTheme(
    mode: NeoThemeMode.light,
    lightTheme: MyBrandThemeLight(),
    darkTheme: MyBrandThemeDark(),
  );
  ```

  ```dart Get Current State lines theme={null}
  // Get current theme mode
  final currentMode = ref.read(neoCurrentThemeProvider.notifier).getSelectedThemeMode();

  // Watch current theme
  final theme = ref.watch(neoCurrentThemeProvider);
  ```
</CodeGroup>

## Enums

### NeoThemeMode

Controls which theme to display based on different strategies.

* `system`: Automatically follows device's system theme setting and updates in real-time.
* `light`: Always uses the light theme regardless of system settings.
* `dark`: Always uses the dark theme regardless of system settings.