Theming
Start the theme
Call ThemeService.initialize() once, when the app starts. It applies the stored theme, follows the system's mode, and stores each change. Until then the page stays light at the default size; on the server it does nothing. This is the docs site's own app.config.ts:
import type { ApplicationConfig } from '@angular/core';
import { inject, provideAppInitializer, provideZonelessChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { ThemeService } from 'tableau-ui-angular/theme';
import { routes } from './app.routes';
export const appConfig: ApplicationConfig = {
providers: [
provideZonelessChangeDetection(),
provideRouter(routes),
// Applies the stored theme before the first render, and keeps it applied; on the server it does nothing
provideAppInitializer(() => {
inject(ThemeService).initialize();
}),
],
};Dark mode and font size
setColorMode() takes light, dark or auto, which follows the system; the service puts the dark-mode class on the root element and the body. setFontSize() sets the base size, which the library's other sizes follow, and reset() goes back to the default. $theme and $appliedThemeMode give the current choice as signals, and theme$ and appliedThemeMode$ as observables.
Showing the light mode at 12px. The choice is stored in the browser for the next visit.
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiButtonToggleModule } from 'tableau-ui-angular/button-toggle';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { ThemeService } from 'tableau-ui-angular/theme';
@Component({
selector: 'app-theme-switcher-example',
imports: [TableauUiButtonModule, TableauUiButtonToggleModule, TableauUiCommonModule, TableauUiFormFieldModule],
templateUrl: './theme-switcher.example.html',
styleUrl: './theme-switcher.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ThemeSwitcherExampleComponent {
protected readonly theme = inject(ThemeService);
protected readonly $mode = computed(() => this.theme.$theme().mode);
protected readonly $fontSize = computed(() => parseInt(this.theme.$theme().fontSize, 10));
// 'auto' follows the system's mode, and $appliedThemeMode says which one shows
protected setMode(mode: 'auto' | 'dark' | 'light' | undefined) {
if (mode) {
this.theme.setColorMode(mode);
}
}
// The base size, in --twc-font-size-body; the library's other sizes are relative to it
protected setFontSize(event: Event) {
const size = Number((event.target as HTMLInputElement).value);
if (size >= 10 && size <= 24) {
this.theme.setFontSize(`${size}px`);
}
}
}CSS custom properties
Every colour, font and size is a custom property, set on :root and, for dark mode, on :root.dark-mode, body.dark-mode, since the theme service puts the class on both. Set one on an element to change it inside that element, or on those selectors in styles.scss to change it for the app: a colour set on :root.dark-mode alone stops at the body, which has its own.
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiCheckboxModule } from 'tableau-ui-angular/checkbox';
@Component({
selector: 'app-theme-override-example',
imports: [TableauUiButtonModule, TableauUiCheckboxModule],
templateUrl: './theme-override.example.html',
styleUrl: './theme-override.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ThemeOverrideExampleComponent {}Colours
| Property | Now | Light | Dark |
|---|---|---|---|
--twc-color-base | rgb(255 255 255) | rgb(27, 27, 27) | |
--twc-color-base-highlight | rgb(250 250 250) | rgb(30 30 30) | |
--twc-color-text | rgb(0 0 0 / 80%) | rgb(255 255 255 / 87%) | |
--twc-color-text-strong | rgb(0 0 0 / 100%) | rgb(255 255 255) | |
--twc-color-text-light | rgb(102 102 102) | rgb(180 180 180) | |
--twc-color-link | rgb(26 105 158) | rgb(98, 137, 163) | |
--twc-color-primary-r | 5 | 5 | |
--twc-color-primary-g | 98 | 98 | |
--twc-color-primary-b | 138 | 138 | |
--twc-color-primary | rgb(var(--twc-color-primary-r), var(--twc-color-primary-g), var(--twc-color-primary-b)) | rgb(var(--twc-color-primary-r), var(--twc-color-primary-g), var(--twc-color-primary-b)) | |
--twc-color-primary-light | rgb(207 233 254) | rgb(27, 48, 68) | |
--twc-color-primary-dark | rgb(2 50 72) | rgb(14, 151, 209) | |
--twc-color-on-primary | rgb(234 245 254) | rgb(226, 226, 226) | |
--twc-color-primary-on-base | var(--twc-color-primary) | rgb(80 185 230) | |
--twc-color-error | rgb(190 10 30) | rgb(255 133 133) | |
--twc-color-error-dark | rgb(100 1 3) | rgb(211, 122, 122) | |
--twc-color-error-light | rgb(255 203 203) | rgb(100 1 3) | |
--twc-color-success | rgb(0 128 0) | rgb(58, 167, 58) | |
--twc-color-success-light | rgb(212 248 212) | rgb(29, 87, 29) | |
--twc-color-disabled | rgb(205 205 205) | rgb(90 90 90) | |
--twc-color-text-gray | rgb(145 145 145) | rgb(130 130 130) | |
--twc-color-highlight | rgb(220 220 220) | rgb(60 60 60) | |
--twc-color-mouse-highlight | rgb(235 235 235) | rgb(41, 40, 40) | |
--twc-color-border-light | rgb(203 203 203) | rgb(70 70 70) | |
--twc-color-border | rgb(116 116 116) | rgb(100 100 100) | |
--twc-color-border-dark | rgb(46 46 46) | rgb(140 140 140) | |
--twc-color-border-dark-disabled | rgb(174 174 174) | rgb(80 80 80) | |
--twc-color-focused-input | rgb(10 91 171) | rgb(60 130 200) | |
--twc-tab-color-active-underline | rgb(92 92 92) | rgb(160 160 160) | |
--twc-tab-color-inactive-underline | rgb(230 230 230) | rgb(50 50 50) | |
--twc-modal-color-header | rgb(243 243 243) | rgb(40 40 40) | |
--twc-modal-color-box-shadow | rgba(0, 0, 0, 0.35) | rgba(112, 112, 112, 0.35) | |
--twc-modal-color-backdrop | rgb(245, 245, 245, 0.33) | rgba(31, 31, 31, 0.644) | |
--twc-dialog-box-shadow | 0 2px 16px 0 rgb(46 46 46 / 15%) | 0 2px 16px 0 rgba(77, 77, 77, 0.4) |
Fonts, sizes, menus and inputs
| Property | Default |
|---|---|
--twc-font-family | 'Benton Sans', 'Roboto', arial, helvetica, sans-serif |
--twc-low-dpi-font-family | 'Benton Sans Low-DPI', 'Roboto', arial, helvetica, sans-serif |
--twc-font-size-body | 12px |
--twc-font-size-body-large | 1.1em |
--twc-font-size-subtitle | 1.3em |
--twc-font-size-title | 1.4em |
--twc-font-size-page-title | 1.6em |
--twc-menu-border-radius | 1px |
--twc-input-border-radius | 1px |
--twc-menu-highlight-outline | 1px solid var(--twc-color-text-gray) |
--twc-menu-highlight-outline-offset | -1px |
--twc-menu-selected-background-color | rgb(var(--twc-color-primary-r) var(--twc-color-primary-g) var(--twc-color-primary-b) / 10%) |
--twc-menu-selected-outline | 1px solid var(--twc-color-primary-on-base) |
--twc-menu-selected-outline-offset | -1px |
--twc-input-border | 1px solid var(--twc-color-border) |
Accessibility
Error text, the primary drawn as text, an icon, a border or the checkbox's and the radio button's focus rings, and the error and primary buttons' labels read at 4.5:1 or more, the contrast WCAG asks of body text and more than the 3:1 it asks of borders and rings, on every surface the library draws them on, at rest and under the pointer, in light and in dark. A spec in the library reads each pair below in both themes, in Chromium and Firefox.
| Colour | Background | Where |
|---|---|---|
--twc-color-error | --twc-color-base | Error text on the page, a dialog's body or an input; a stroked error button's label |
--twc-color-error | --twc-color-primary-light | Error text on a table's selected row |
--twc-color-error | --twc-color-highlight | Error text on the keyboard highlight in a list, a select, an autocomplete or a menu |
--twc-color-error | --twc-modal-color-header | Error text on a modal's header |
--twc-color-error | --twc-color-mouse-highlight | A stroked error button's label under the pointer |
--twc-color-base | --twc-color-error | A raised error button's label |
--twc-color-base | --twc-color-error-dark | A raised error button's label under the pointer |
--twc-color-primary-on-base | --twc-color-base | Primary text and icons on the page, a dialog or a menu; a stroked primary button's label and border; a checkbox's and a radio button's focus ring, a selected option's outline, a column's resize line |
--twc-color-primary-on-base | --twc-color-mouse-highlight | A stroked primary button's label and border under the pointer |
--twc-color-primary-on-base | --twc-color-highlight | A primary menu item on the highlight; a selected option's outline on the keyboard highlight |
--twc-color-primary-on-base | --twc-color-primary-light | An info snack's icon, border and timer; a primary icon on a table's selected row |
--twc-color-primary-on-base | --twc-modal-color-header | Primary text or an icon on a modal's header |
--twc-color-on-primary | --twc-color-primary | A raised primary button's label; a checked button toggle option's label |
--twc-color-base | --twc-color-primary-dark | A raised primary button's label under the pointer |
For its own error text, such as a negative number, an app reads var(--twc-color-error) rather than copying the value, so the text follows the theme. Text an app puts on --twc-color-error, such as a count badge, takes --twc-color-base, as the raised error button now does: a light text there reads below 4.5:1 on the dark theme's red. An app that sets one of these colours keeps each pair at 4.5:1, --twc-color-base on --twc-color-error included.
The library draws the primary on the page's surfaces, as text, icons, a stroked button, the checkbox's and the radio button's focus rings or a selected option's outline, in --twc-color-primary-on-base. In light it is --twc-color-primary itself; in dark, where the primary is 2.56:1 on the base, it is a lighter blue. Fills keep --twc-color-primary under --twc-color-on-primary, and a raised primary button's label under the pointer takes --twc-color-base. An app that sets --twc-color-primary sets --twc-color-primary-on-base beside it, at 4.5:1 on --twc-color-base, --twc-color-mouse-highlight and --twc-color-highlight, as the green row of the sample above does: in dark always, on :root.dark-mode, body.dark-mode, and in light wherever it isn't :root, since on :root the light one follows it by itself. An app that sets --twc-color-primary-dark keeps --twc-color-base on it at 4.5:1; --twc-color-on-primary colours the raised label at rest only.