Styling and theming in Dojo

Example

Given the following CSS module file for a widget:

src/styles/MyWidget.m.css

.myWidgetClass {
    font-variant: small-caps;
}

.myWidgetExtraClass {
    font-style: italic;
}

This stylesheet can be used within a corresponding widget as follows:

src/widgets/MyWidget.ts

import { create, tsx } from '@dojo/framework/core/vdom';

import * as css from '../styles/MyWidget.m.css';

const factory = create();

export default factory(function MyWidget() {
    return <div classes={[css.myWidgetClass, css.myWidgetExtraClass]}>Hello from a Dojo widget!</div>;
});

When inspecting the CSS classes of these sample widgets in a built application, they will not contain myWidgetClass and myWidgetExtraClass, but rather obfuscated CSS class names similar to MyWidget-m__myWidgetClass__33zN8 and MyWidget-m__myWidgetExtraClass___g3St.

These obfuscated class names are localized to MyWidget elements, and are determined by Dojo's CSS modules build process. With this mechanism it is possible for other widgets in the same application to also use the myWidgetClass class name with different styling rules, and not encounter any conflicts between each set of styles.

Warning: The obfuscated CSS class names should be considered unreliable and may change with a new build of an application, so developers should not explicitly reference them (for examples if attempting to target an element from elsewhere in an application).

CSS custom properties

Dojo allows use of modern CSS features such as custom properties and var() to help abstract and centralize common styling properties within an application.

Rather than having to specify the same values for colors or fonts in every widget's CSS module, abstract custom properties can instead be referenced by name, with values then provided in a centralized CSS :root pseudo-class. This separation allows for much simpler maintenance of common styling concerns across an entire application.

For example:

src/themes/variables.css

:root {
    /* different sets of custom properties can be used if an application supports more than one possible theme */
    --light-background: lightgray;
    --light-foreground: black;

    --dark-background: black;
    --dark-foreground: lightgray;

    --padding: 32px;
}

src/themes/myDarkTheme/MyWidget.m.css

@import '../variables.css';

.root {
    margin: var(--padding);

    color: var(--dark-foreground);
    background: var(--dark-background);
}

Note that the :root pseudo-class is global within a webpage, but through Dojo's use of CSS modules, :root properties could potentially be specified in many locations across an application. However, Dojo does not guarantee the order in which CSS modules are processed, so to ensure consistency of which properties appear in :root, it is recommended that applications use a single :root definition within a centralized variables.css file in the application's codebase. This centralized variables file is a regular CSS file (not a CSS module) and can be @imported as such in any CSS modules that require custom property values.

Dojo's default build process propagates custom properties as-is into the application's output stylesheets. This is fine when only targeting evergreen browsers, but can be problematic when also needing to target browsers that do not implement the CSS custom properties standard (such as IE). To get around this, applications can be built in legacy mode (dojo build app --legacy), in which case Dojo will resolve the values of custom properties at build time and duplicate them in the output stylesheets. One value will contain the original var() reference, and the second will be the resolved value that legacy browsers can fall back to when they are unable to process the var() values.

CSS module composition

Applying a theme to a Dojo widget results in the widget's default styling classes being entirely overridden by those provided in the theme. This can be problematic when only a subset of properties in a given styling class need to be modified through a theme, while the remainder can stay as default.

CSS module files in Dojo applications can leverage composes: functionality to apply sets of styles from one class selector to another. This can be useful when creating a new theme that tweaks an existing one, as well as for general abstraction of common sets of styling properties within a single theme (note that CSS custom properties are a more standardized way of abstracting values for individual style properties).

Warning: Use of composes: can prove brittle, for example when extending a third-party theme that is not under direct control of the current application. Any change made by a third-party could break an application theme that composes the underlying theme, and such breakages can be problematic to pin down and resolve.

However, careful use of this feature can be helpful in large applications. For example, centralizing a common set of properties:

src/themes/common/ButtonBase.m.css

.buttonBase {
    margin-right: 10px;
    display: inline-block;
    font-size: 14px;
    text-align: left;
    background-color: white;
}

src/themes/myBlueTheme/MyButton.m.css

.root {
    composes: buttonBase from '../common/ButtonBase.m.css';
    background-color: blue;
}