---
title: theme.json Theme Configuration
summary: "Describes the format of the theme.json configuration file for declaring light and dark theme variables."
questions:
  - What is the purpose of the theme.json file?
  - What is the configuration format of theme.json?
  - How do I declare light and dark theme variables in theme.json?
  - How are declared theme variables applied to app.json?
  - Which fields in app.json support theme variables from theme.json?
---

# theme.json Theme Configuration

`theme.json` is the theme configuration file used to define variable values for the `light` and `dark` themes. Once configured, the miniapp framework automatically switches to the corresponding color scheme based on the system theme.

## Steps

1. Configure `themeLocation` in `app.json` to specify the path to `theme.json`. For example, if you add `theme.json` in the root directory, configure `"themeLocation": "theme.json"`.
2. Define theme variables in `theme.json`.
3. Reference variables with the `@` prefix in `app.json`.

## Configuration Format

`theme.json` must include the following properties:

| Property | Type   | Required | Description                          |
| -------- | ------ | -------- | ------------------------------------ |
| light    | object | Yes      | Variable definitions for light mode  |
| dark     | object | Yes      | Variable definitions for dark mode   |

Variables and values are defined in `key: value` format under `light` and `dark`:

```json
{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black",
    "bgColor": "#ffffff"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white",
    "bgColor": "#1f1f1f"
  }
}
```

## Supported Fields for Theme Variables

After declaring theme variables, you can apply them using the `@` prefix to the following fields in `app.json`:

- Global `window` configuration and page configuration fields:
  - navigationBarBackgroundColor
  - navigationBarTextStyle
  - backgroundColor
  - backgroundTextStyle
  - backgroundColorTop
  - backgroundColorBottom
- Global `tabBar` configuration fields:
  - color
  - selectedColor
  - backgroundColor
  - borderStyle
  - list
    - iconPath
    - selectedIconPath

## Configuration Example

### app.json

> The example omits configuration items unrelated to theming.

```json
{
  "themeLocation": "theme.json",
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle",
    "backgroundColor": "@bgColor",
    "backgroundTextStyle": "@bgTxtStyle"
  },
  "tabBar": {
    "color": "@tabFontColor",
    "selectedColor": "@tabSelectedColor",
    "backgroundColor": "@tabBgColor",
    "borderStyle": "@tabBorderStyle",
    "list": [
      {
        "iconPath": "@iconPath1",
        "selectedIconPath": "@selectedIconPath1"
      },
      {
        "iconPath": "@iconPath2",
        "selectedIconPath": "@selectedIconPath2"
      }
    ]
  }
}
```

### theme.json

```json
{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black",
    "bgColor": "#ffffff",
    "bgTxtStyle": "light",
    "tabFontColor": "#000000",
    "tabSelectedColor": "#3cc51f",
    "tabBgColor": "#ffffff",
    "tabBorderStyle": "black",
    "iconPath1": "image/icon1_light.png",
    "selectedIconPath1": "image/selected_icon1_light.png",
    "iconPath2": "image/icon2_light.png",
    "selectedIconPath2": "image/selected_icon2_light.png"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white",
    "bgColor": "#1f1f1f",
    "bgTxtStyle": "dark",
    "tabFontColor": "#ffffff",
    "tabSelectedColor": "#51a937",
    "tabBgColor": "#191919",
    "tabBorderStyle": "white",
    "iconPath1": "image/icon1_dark.png",
    "selectedIconPath1": "image/selected_icon1_dark.png",
    "iconPath2": "image/icon2_dark.png",
    "selectedIconPath2": "image/selected_icon2_dark.png"
  }
}
```

### Page Configuration

Theme variables can also be referenced in page `.json` configuration files:

```json
{
  "navigationBarBackgroundColor": "@navBgColor",
  "navigationBarTextStyle": "@navTxtStyle"
}
```

## Get Current System Theme

The return value of `ty.getSystemInfo` or `ty.getSystemInfoSync` includes a `theme` attribute with a value of either `light` or `dark`.

## Listen for Theme Change Events

Two methods are supported:

1. Pass the `onThemeChange` callback in `App()`:

```javascript
App({
  onThemeChange(res) {
    console.log('Current theme:', res.theme); // 'light' or 'dark'
  }
});
```

2. Use `ty.onThemeChange` to listen and `ty.offThemeChange` to unsubscribe:

```javascript
const handler = function (res) {
  console.log('Theme changed:', res.theme);
};

ty.onThemeChange(handler);

// Unsubscribe when no longer needed
ty.offThemeChange(handler);
```