1# WithTheme
2
3The **WithTheme** component is designed to customize the theme style for a specific part of an application page. It allows for the setting of light and dark modes for child components, as well as the use of custom color schemes.
4
5> **NOTE**
6>
7> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Child Components
10
11This component supports only one child component.
12
13## APIs
14
15WithTheme(options: WithThemeOptions)
16
17**Atomic service API**: This API can be used in atomic services since API version 12.
18
19**System capability**: SystemCapability.ArkUI.ArkUI.Full
20
21**Parameters**
22
23| Name                           | Type                                 | Mandatory | Description    |
24|--------------------------------|---------------------------------------|-----|---------------|
25| options | [WithThemeOptions](#withthemeoptions) | Yes  | Color scheme for components within the scope.|
26
27## Attributes
28
29The [universal attributes](ts-universal-attributes-size.md) are not supported.
30
31## Events
32
33The [universal events](ts-universal-events-click.md) are not supported.
34
35## WithThemeOptions
36
37Defines the default theme and color mode for components within the **WithTheme** scope.
38
39**Atomic service API**: This API can be used in atomic services since API version 12.
40
41**System capability**: SystemCapability.ArkUI.ArkUI.Full
42
43| Name       | Type                              | Mandatory| Description               |
44|------------------------|---------------------------------------------------------| ---- |------------------------------------------------------------------|
45| theme     | [CustomTheme](../js-apis-arkui-theme.md#customtheme)    | No  | Default theme for components in the **WithTheme** scope.<br> Default value: **undefined**, indicating that the styles will follow the system's default theme.<br>|
46| colorMode | [ThemeColorMode](#themecolormode10) | No  | Color mode for components in the **WithTheme** scope.<br>Default value: **ThemeColorMode.System**<br>      |
47
48## ThemeColorMode<sup>10+</sup>
49
50**Atomic service API**: This API can be used in atomic services since API version 11.
51
52**System capability**: SystemCapability.ArkUI.ArkUI.Full
53
54| Name    | Description      |
55| ------ | ---------- |
56| SYSTEM | System color mode.|
57| LIGHT  | Light color mode. |
58| DARK   | Dark color mode. |
59
60## Example
61
62This example demonstrates how to use **WithTheme** to set the color mode, which is effective only when a **dark.json** resource file is included.
63
64![resources_dark](figures/resources_dark.png)
65
66Example of the **dark.json** file content:
67  ```ts
68    {
69      "color": [
70        {
71          "name": "start_window_background",
72          "value": "#FFFFFF"
73        }
74      ]
75    }
76  ```
77
78```ts
79// Specify the local color mode.
80@Entry
81@Component
82struct Index {
83  build() {
84    Column() {
85    // System default
86      Column() {
87        Text('WithTheme not used')
88          .fontSize(40)
89          .fontWeight(FontWeight.Bold)
90      }
91      .justifyContent(FlexAlign.Center)
92      .width('100%')
93      .height('33%')
94      .backgroundColor($r('sys.color.background_primary'))
95      // Set the component to the dark mode.
96      WithTheme({ colorMode: ThemeColorMode.DARK }) {
97        Column() {
98          Text('WithTheme')
99            .fontSize(40)
100            .fontWeight(FontWeight.Bold)
101          Text('DARK')
102            .fontSize(40)
103            .fontWeight(FontWeight.Bold)
104        }
105        .justifyContent(FlexAlign.Center)
106        .width('100%')
107        .height('33%')
108        .backgroundColor($r('sys.color.background_primary'))
109      }
110      // Set the component to the light mode.
111      WithTheme({ colorMode: ThemeColorMode.LIGHT }) {
112        Column() {
113          Text('WithTheme')
114            .fontSize(40)
115            .fontWeight(FontWeight.Bold)
116          Text('LIGHT')
117            .fontSize(40)
118            .fontWeight(FontWeight.Bold)
119        }
120        .justifyContent(FlexAlign.Center)
121        .width('100%')
122        .height('33%')
123        .backgroundColor($r('sys.color.background_primary'))
124      }
125    }
126    .height('100%')
127    .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.END, SafeAreaEdge.BOTTOM, SafeAreaEdge.START])
128  }
129}
130```
131![withThemeColorMode](figures/witheThemeColorMode.png)
132
133```ts
134// Customize the default theme for components in the WithTheme scope.
135import { CustomTheme, CustomColors } from '@kit.ArkUI';
136
137class GreenColors implements CustomColors {
138  fontPrimary = '#ff049404';
139  fontEmphasize = '#FF00541F';
140  fontOnPrimary = '#FFFFFFFF';
141  compBackgroundTertiary = '#1111FF11';
142  backgroundEmphasize = '#FF00541F';
143  compEmphasizeSecondary = '#3322FF22';
144}
145
146class RedColors implements CustomColors {
147  fontPrimary = '#fff32b3c';
148  fontEmphasize = '#FFD53032';
149  fontOnPrimary = '#FFFFFFFF';
150  compBackgroundTertiary = '#44FF2222';
151  backgroundEmphasize = '#FFD00000';
152  compEmphasizeSecondary = '#33FF1111';
153}
154
155class PageCustomTheme implements CustomTheme {
156  colors?: CustomColors
157
158  constructor(colors: CustomColors) {
159    this.colors = colors
160  }
161}
162
163@Entry
164@Component
165struct IndexPage {
166  static readonly themeCount = 3;
167  themeNames: string[] = ['System', 'Custom (green)', 'Custom (red)'];
168  themeArray: (CustomTheme | undefined)[] = [
169    undefined, // System
170    new PageCustomTheme(new GreenColors()),
171    new PageCustomTheme(new RedColors())
172  ]
173  @State themeIndex: number = 0;
174
175  build() {
176    Column() {
177      Column({ space: '8vp' }) {
178        Text('WithTheme not used')
179        // Click the button to change the theme.
180        Button(`Switch Theme: ${this.themeNames[this.themeIndex]}`)
181          .onClick(() => {
182            this.themeIndex = (this.themeIndex + 1) % IndexPage.themeCount;
183          })
184
185        // Default button color
186        Button('Button.style(NORMAL) with System Theme')
187          .buttonStyle(ButtonStyleMode.NORMAL)
188        Button('Button.style(EMP..ED) with System Theme')
189          .buttonStyle(ButtonStyleMode.EMPHASIZED)
190        Button('Button.style(TEXTUAL) with System Theme')
191          .buttonStyle(ButtonStyleMode.TEXTUAL)
192      }
193      .margin({
194        top: '50vp'
195      })
196
197      WithTheme({ theme: this.themeArray[this.themeIndex] }) {
198        // WithTheme scope
199        Column({ space: '8vp' }) {
200          Text('WithTheme used')
201          Button('Button.style(NORMAL) with Custom Theme')
202            .buttonStyle(ButtonStyleMode.NORMAL)
203          Button('Button.style(EMP..ED) with Custom Theme')
204            .buttonStyle(ButtonStyleMode.EMPHASIZED)
205          Button('Button.style(TEXTUAL) with Custom Theme')
206            .buttonStyle(ButtonStyleMode.TEXTUAL)
207        }
208        .width('100%')
209      }
210    }
211  }
212}
213```
214![withThemeSystem](figures/withThemeChangeTheme.gif)
215