@ohos.arkui.theme (Theme)
You can define a custom theme to apply to components in your application.
NOTE
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.
The APIs of this module can be used only in the stage model.
Modules to Import
import { Theme, ThemeControl, CustomColors, Colors, CustomTheme, CustomDarkColors } from '@kit.ArkUI';
Theme
Defines the Theme object in use, which can be obtained through onWillApplyTheme.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| colors | Colors | No | No | Color resources of the theme. |
Colors
Defines the color resources of a theme.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| brand | ResourceColor | No | No | Brand color. Affected components: TextInput and Search |
| warning | ResourceColor | No | No | Warning color. Affected components: TipsDialog, AlertDialog, CustomContentDialog, Badge, and Button |
| alert | ResourceColor | No | No | Alert color. Affected components: N/A |
| confirm | ResourceColor | No | No | Confirmation color. Affected components: N/A |
| fontPrimary | ResourceColor | No | No | Primary font color. Affected components: EditableTitleBar, LoadingDialog, TipsDialog, ConfirmDialog, AlertDialog, SelectDialog, CustomContentDialog, Swiper, Text, SubHeader, ProgressButton, AlphabetIndexer, Popup, Select, Chip, ToolBar, Menu, TextInput, Search, TimePicker, DatePicker, TextPicker, ComposeListItem, and TreeView. Since API version 26.0.0, CalendarPicker, UIPickerComponent, RichEditor, MenuItem, MenuItemGroup, and Counter are added. |
| fontSecondary | ResourceColor | No | No | Secondary font color. Affected components: EditableTitleBar, AlertDialog, CustomContentDialog, SubHeader, AlphabetIndexer, Popup, TextInput, Search, ComposeListItem, TreeView, and TextClock. Since API version 26.0.0, MenuItem and MenuItemGroup are added. |
| fontTertiary | ResourceColor | No | No | Tertiary font color. Affected components: ComposeListItem |
| fontFourth | ResourceColor | No | No | Fourth-level font color. Affected components: N/A |
| fontEmphasize | ResourceColor | No | No | Emphasis font color. Affected components: TipsDialog, ConfirmDialog, AlertDialog, SelectDialog, CustomContentDialog, SubHeader, AlphabetIndexer, Popup, Button, Select, ToolBar, Search, TimePicker, DatePicker, and TextPicker. Since API version 26.0.0, RichEditor is added. |
| fontOnPrimary | ResourceColor | No | No | Primary inverted font color used on color background. Affected components: Badge, Button, and Chip |
| fontOnSecondary | ResourceColor | No | No | Secondary inverted font color used on color background. Affected components: N/A |
| fontOnTertiary | ResourceColor | No | No | Tertiary inverted font color used on color background. Affected components: N/A |
| fontOnFourth | ResourceColor | No | No | Fourth-level inverted font color used on color background. Affected components: N/A |
| iconPrimary | ResourceColor | No | No | Primary icon color. Affected components: EditableTitleBar, Swiper, ToolBar, and TreeView. Since API version 26.0.0, MenuItem is added. |
| iconSecondary | ResourceColor | No | No | Secondary icon color. Affected components: LoadingDialog, SubHeader, Popup, Chip, Search, and TreeView. Since API version 26.0.0, LoadingProgress is added. |
| iconTertiary | ResourceColor | No | No | Tertiary icon color. Affected components: SubHeader |
| iconFourth | ResourceColor | No | No | Fourth-level icon color. Affected components: Checkbox, CheckboxGroup, and Radio |
| iconEmphasize | ResourceColor | No | No | Emphasis icon color. Affected components: ToolBar |
| iconSubEmphasize | ResourceColor | No | No | Color of the emphasis auxiliary icon. Affected components: N/A |
| iconOnPrimary | ResourceColor | No | No | Primary inverted icon color used on color background. Affected components: Checkbox, CheckboxGroup, and Radio |
| iconOnSecondary | ResourceColor | No | No | Secondary inverted icon color used on color background. Affected components: Chip |
| iconOnTertiary | ResourceColor | No | No | Tertiary inverted icon color used on color background. Affected components: N/A |
| iconOnFourth | ResourceColor | No | No | Fourth-level inverted icon color used on color background. Affected components: ProgressButton |
| backgroundPrimary | ResourceColor | No | No | Primary background color (solid, opaque). Affected components: TextInput and QRCode |
| backgroundSecondary | ResourceColor | No | No | Secondary background color (solid, opaque). Affected components: N/A |
| backgroundTertiary | ResourceColor | No | No | Tertiary background color (solid, opaque). Affected components: N/A |
| backgroundFourth | ResourceColor | No | No | Fourth-level background color (solid, opaque). Affected components: N/A |
| backgroundEmphasize | ResourceColor | No | No | Emphasis background color (solid, opaque). Affected components: Progress, Button, and Slider |
| compForegroundPrimary | ResourceColor | No | No | Foreground. Affected components: QRCode |
| compBackgroundPrimary | ResourceColor | No | No | White background. Affected components: N/A |
| compBackgroundPrimaryTran | ResourceColor | No | No | White transparent background. Affected components: N/A |
| compBackgroundPrimaryContrary | ResourceColor | No | No | Always-on background. Affected components: Toggle and Slider |
| compBackgroundGray | ResourceColor | No | No | Gray background. Affected components: N/A |
| compBackgroundSecondary | ResourceColor | No | No | Secondary background. Affected components: Swiper and Slider |
| compBackgroundTertiary | ResourceColor | No | No | Tertiary background. Affected components: EditableTitleBar, Progress, AlphabetIndexer, Button, Select, Toggle, Chip, TextInput, and Search. Since API version 26.0.0, UIPickerComponent and TextPicker are added. |
| compBackgroundEmphasize | ResourceColor | No | No | Emphasis background. Affected components: Swiper, Toggle, Chip, Checkbox, CheckboxGroup, and Radio |
| compBackgroundNeutral | ResourceColor | No | No | Black, neutral, emphasis background. Affected components: PatternLock |
| compEmphasizeSecondary | ResourceColor | No | No | 20% emphasis background color. Affected components: Progress, ProgressButton, AlphabetIndexer, Select, and Toggle |
| compEmphasizeTertiary | ResourceColor | No | No | 10% emphasis background color. Affected components: N/A |
| compDivider | ResourceColor | No | No | Common divider color. Affected components: SelectDialog, PatternLock, and Divider. Since API version 26.0.0, UIPickerComponent, TextPicker, MenuItem, MenuItemGroup, and Select are added. |
| compCommonContrary | ResourceColor | No | No | Common inverted color. Affected components: N/A |
| compBackgroundFocus | ResourceColor | No | No | Background color in the focused state. Affected components: N/A |
| compFocusedPrimary | ResourceColor | No | No | Primary inverted color in the focused state. Affected components: N/A |
| compFocusedSecondary | ResourceColor | No | No | Secondary inverted color in the focused state. Affected components: N/A |
| compFocusedTertiary | ResourceColor | No | No | Tertiary inverted color in the focused state. Affected components: Scroll |
| interactiveHover | ResourceColor | No | No | Common interactive color for the hover state. Affected components: EditableTitleBar, Chip, and TreeView. Since API version 26.0.0, RichEditor, MenuItem, and Select are added. |
| interactivePressed | ResourceColor | No | No | Common interactive color for the pressed state. Affected components: EditableTitleBar, Chip, and TreeView. Since API version 26.0.0, RichEditor is added. |
| interactiveFocus | ResourceColor | No | No | Common interactive color for the focused state. Affected components: EditableTitleBar, Chip, and TreeView |
| interactiveActive | ResourceColor | No | No | Common interactive color for the active state. Affected components: TreeView |
| interactiveSelect | ResourceColor | No | No | Common interactive color for the selected state. Affected components: TreeView |
| interactiveClick | ResourceColor | No | No | Common interactive color for the clicked state. Affected components: MenuItem and Select are added since API version 26.0.0. |
CustomTheme
Defines a custom theme object.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| colors | CustomColors | No | Yes | Custom light theme color resources. Atomic service API: This API can be used in atomic services since API version 12. |
| darkColors20+ | CustomDarkColors | No | Yes | Custom dark theme color resources. Note: If darkColors is not configured, the color values will default to those specified in the colors configuration for light mode and will not adapt to dark mode changes, unless the colors are defined using resources from the dark directory. Atomic service API: This API can be used in atomic services since API version 20. |
CustomColors
type CustomColors = Partial<Colors>
Defines the type for custom theme color resources.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| Partial<Colors> | Type representing customizable theme color resources. |
CustomDarkColors20+
type CustomDarkColors = Partial<Colors>
Defines the type for dark theme color resources.
Atomic service API: This API can be used in atomic services since API version 20.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| Partial<Colors> | Type representing customizable dark theme color resources. |
ThemeControl
Implements a ThemeControl object to apply the custom theme to the components in the application.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
setDefaultTheme
setDefaultTheme(theme: CustomTheme): void
Sets a custom theme as the default, application-level theme, applying it to all components within the application. When using this API within a page, ensure that the API is called before the page's build API executes. When using this API within a UIAbility, ensure that the API is called in the callback after windowStage.loadContent during the onWindowStageCreate lifecycle phase. For a complete implementation example, see Setting Custom Theme Colors for Application Components.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| theme | CustomTheme | Yes | Custom theme to set. |
Example
import { CustomTheme, CustomColors, ThemeControl } from '@kit.ArkUI';
// Custom theme color
class BlueColors implements CustomColors {
fontPrimary = "#FF707070";
backgroundPrimary = "#FF2787D9";
brand = "#FFEEAAFF"; // Brand color.
}
class PageCustomTheme implements CustomTheme {
colors?: CustomColors;
constructor(colors: CustomColors) {
this.colors = colors;
}
}
// Create an instance.
const BlueColorsTheme = new PageCustomTheme(new BlueColors());
// Call ThemeControl.setDefaultTheme before page build to set the default application style to BlueColorsTheme.
ThemeControl.setDefaultTheme(BlueColorsTheme);
@Entry
@Component
struct Index {
build() {
Row() {
Column() {
// Apply fontPrimary to the text color.
Text('This is a piece of text.')
.fontSize(30)
.fontWeight(FontWeight.Bold)
.margin('5%')
// Apply backgroundPrimary to the QR code background color.
QRCode('Hello')
.width(100)
.height(100)
// Apply brand to the input box cursor color.
TextInput({placeholder: 'input your word...'})
.width('80%')
.height(40)
.margin(20)
}
.width('100%')
}
.height('100%')
}
}
