1# @ohos.arkui.Theme (Theme)
2
3You can define a custom theme to apply to components in your application.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { Theme, ThemeControl, CustomColors, Colors, CustomTheme } from '@kit.ArkUI';
13```
14
15## Theme
16
17Defines the **Theme** object in use, which can be obtained through [onWillApplyTheme](arkui-ts/ts-custom-component-lifecycle.md#onwillapplytheme12).
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23| Name | Type               | Readable | Writable | Description      |
24| ------ |-------------------|-----|-----|----------|
25| colors | [Colors](#colors) | No  | No  |  Color resources of the theme. |
26
27## Colors
28
29Defines the color resources of a theme.
30
31**Atomic service API**: This API can be used in atomic services since API version 12.
32
33**System capability**: SystemCapability.ArkUI.ArkUI.Full
34
35| Name                          | Type                                                | Readable | Writable | Description              |
36|-------------------------------|-----------------------------------------------------|-----|-----|------------------|
37| brand                         | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Brand color.            |
38| warning                       | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Warning color.          |
39| alert                         | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Alert color.          |
40| confirm                       | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Confirmation color.            |
41| fontPrimary                   | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Primary font color.       |
42| fontSecondary                 | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary font color.       |
43| fontTertiary                  | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary font color.       |
44| fontFourth                    | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Fourth-level font color.       |
45| fontEmphasize                 | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Emphasis font color.         |
46| fontOnPrimary                 | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Primary inverted font color used on color background. |
47| fontOnSecondary               | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary inverted font color used on color background. |
48| fontOnTertiary                | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary inverted font color used on color background. |
49| fontOnFourth                  | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Fourth-level inverted font color used on color background. |
50| iconPrimary                   | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Primary icon color.         |
51| iconSecondary                 | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary icon color.         |
52| iconTertiary                  | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary icon color.         |
53| iconFourth                    | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Fourth-level icon color.         |
54| iconEmphasize                 | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Emphasis icon color.         |
55| iconSubEmphasize              | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Color of the emphasis auxiliary icon.       |
56| iconOnPrimary                 | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Primary inverted icon color used on color background. |
57| iconOnSecondary               | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary inverted icon color used on color background. |
58| iconOnTertiary                | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary inverted icon color used on color background. |
59| iconOnFourth                  | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Fourth-level inverted icon color used on color background. |
60| backgroundPrimary             | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Primary background color (solid, opaque). |
61| backgroundSecondary           | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary background color (solid, opaque). |
62| backgroundTertiary            | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary background color (solid, opaque). |
63| backgroundFourth              | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Fourth-level background color (solid, opaque). |
64| backgroundEmphasize           | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Emphasis background color (solid, opaque). |
65| compForegroundPrimary         | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Foreground.            |
66| compBackgroundPrimary         | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | White background.           |
67| compBackgroundPrimaryTran     | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | White transparent background.         |
68| compBackgroundPrimaryContrary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Always-on background.           |
69| compBackgroundGray            | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Gray background.           |
70| compBackgroundSecondary       | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary background.           |
71| compBackgroundTertiary        | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary background.           |
72| compBackgroundEmphasize       | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Emphasis background.           |
73| compBackgroundNeutral         | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Black, neutral, emphasis background.     |
74| compEmphasizeSecondary        | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | 20% emphasis background color.      |
75| compEmphasizeTertiary         | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | 10% emphasis background color.      |
76| compDivider                   | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common divider color.        |
77| compCommonContrary            | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common inverted color.         |
78| compBackgroundFocus           | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Background color in the focused state.        |
79| compFocusedPrimary            | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Primary inverted color in the focused state.      |
80| compFocusedSecondary          | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Secondary inverted color in the focused state.      |
81| compFocusedTertiary           | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Tertiary inverted color in the focused state.      |
82| interactiveHover              | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common interactive color for the hover state.      |
83| interactivePressed            | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common interactive color for the pressed state.      |
84| interactiveFocus              | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common interactive color for the focused state.      |
85| interactiveActive             | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common interactive color for the active state.      |
86| interactiveSelect             | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common interactive color for the selected state.      |
87| interactiveClick              | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No  | No  | Common interactive color for the clicked state.      |
88
89## CustomTheme
90
91Defines a custom theme object.
92
93**Atomic service API**: This API can be used in atomic services since API version 12.
94
95**System capability**: SystemCapability.ArkUI.ArkUI.Full
96
97| Name                          | Type                                                | Read Only | Optional | Description        |
98|-------------------------------|-----------------------------------------------------|-----|-----|------------|
99| colors | [CustomColors](#customcolors) | No  | Yes  | Color resources of the custom theme. |
100
101## CustomColors
102
103type CustomColors = Partial\<Colors>
104
105Defines the color resources of a custom theme.
106
107**Atomic service API**: This API can be used in atomic services since API version 12.
108
109**System capability**: SystemCapability.ArkUI.ArkUI.Full
110
111| Type | Description          |
112|-----|--------------|
113| Partial<[Colors](#colors)>   | Color resources of the custom theme. |
114
115## ThemeControl
116
117Implements a **ThemeControl** object to apply the custom theme to the components in the application.
118
119**Atomic service API**: This API can be used in atomic services since API version 12.
120
121**System capability**: SystemCapability.ArkUI.ArkUI.Full
122
123### setDefaultTheme
124
125setDefaultTheme(theme: [CustomTheme](#customtheme)): void
126
127Sets a custom theme as the default, application-level theme so that it is applied to components in the application.
128
129**Atomic service API**: This API can be used in atomic services since API version 12.
130
131**System capability**: SystemCapability.ArkUI.ArkUI.Full
132
133| Name      | Type                          | Mandatory | Description            |
134|--------------|------------------------------|------|----------------|
135| theme | [CustomTheme](#customtheme)  | Yes   | Custom theme to set. |
136
137**Example**
138
139```ts
140import { CustomTheme, CustomColors, ThemeControl } from '@kit.ArkUI';
141// Custom theme color
142class BlueColors implements CustomColors {
143  fontPrimary = Color.White;
144  backgroundPrimary = Color.Blue;
145  brand = Color.Blue; // Brand color
146}
147
148class PageCustomTheme implements CustomTheme {
149  colors?: CustomColors;
150
151  constructor(colors: CustomColors) {
152    this.colors = colors;
153  }
154}
155// Create an instance.
156const BlueColorsTheme = new PageCustomTheme(new BlueColors());
157// Call ThemeControl.setDefaultTheme before page build to set the default application style to BlueColorsTheme.
158ThemeControl.setDefaultTheme(BlueColorsTheme);
159```
160