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