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

# Set Preferred Theme

> Switch the UIKit theme (light / dark / system) at runtime, effective immediately — Flutter only

> [!NOTE]
>
> **Flutter UIKit only.** `setPreferredTheme` is available in the Flutter UIKit from **4.20.20**. Other platforms switch theme through [Dynamic UI](/uikit/customization/dynamic-ui.md) or the device appearance setting.

## Overview

By default the UIKit resolves its theme from the `preferred_theme` value in your `config.json` at startup. `setPreferredTheme` lets you **override that value at runtime**, and the whole UIKit re-themes immediately — no restart, no config re-sync.

```dart Flutter theme={null}
import 'package:amity_uikit_beta_service/amity_uikit.dart';

// Force a style, or follow the device setting
AmityUIKit().setPreferredTheme(AmityThemeStyle.dark);
AmityUIKit().setPreferredTheme(AmityThemeStyle.light);
AmityUIKit().setPreferredTheme(AmityThemeStyle.system);
```

## Styles

| Value | Effect |
| - | - |
| `AmityThemeStyle.light` | Force the light theme |
| `AmityThemeStyle.dark` | Force the dark theme |
| `AmityThemeStyle.system` | Follow the device dark-mode setting |

## How It Works

**1. Call the API**

`AmityUIKit().setPreferredTheme(style)` updates the preferred theme held on the `ConfigRepository` singleton.

**2. Whole tree re-themes**

Every base page, component, and element already watches the config provider, so the change propagates to the entire UIKit tree immediately.

**3. Overrides config.json**

The runtime value takes precedence over `preferred_theme` from `config.json` for the rest of the app session.

> [!NOTE]
>
> The override lives in memory for the current app session. It is **not** persisted by the UIKit — on the next launch the theme resolves from `config.json` again. Persist the user's choice yourself (e.g. in `SharedPreferences`) and re-apply it on startup if you want it to stick.

## Persisting the choice

Save the selection and restore it before your app renders the UIKit:

```dart Flutter theme={null}
import 'package:shared_preferences/shared_preferences.dart';
import 'package:amity_uikit_beta_service/amity_uikit.dart';

const _prefKey = 'preferredTheme';

Future<void> selectTheme(AmityThemeStyle style) async {
  AmityUIKit().setPreferredTheme(style);
  final prefs = await SharedPreferences.getInstance();
  await prefs.setString(_prefKey, style.name);
}

Future<void> restorePreferredTheme() async {
  final prefs = await SharedPreferences.getInstance();
  final saved = prefs.getString(_prefKey);
  if (saved != null) {
    AmityUIKit().setPreferredTheme(
      AmityThemeStyle.values.asNameMap()[saved] ?? AmityThemeStyle.system,
    );
  }
}
```

Call `restorePreferredTheme()` in `main()` before `runApp()`.

## When to Use

✅ In-app **light / dark toggle** driven by a user setting
✅ Following the device appearance without an app restart
✅ Quick theme experiments during development

For remote, non-engineering-driven brand/token changes, use [Dynamic UI](/uikit/customization/dynamic-ui.md) instead.

## Next Steps

> [card] [Dynamic UI](/uikit/customization/dynamic-ui.md)
>
> Remote, config-driven theming

> [card] [Component Styling](/uikit/customization/component-styling.md)
>
> Per-component overrides


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.