Introduction

As an HTML-based technology, Dojo makes use of CSS for styling elements across the framework and for applications developed with it.

Dojo promotes encapsulated structural styling of individual widgets for maximum reuse, as well as simplified presentational theming across all widgets within an application. This pattern gives users a predictable way to style and theme their applications, even when using a mixture of widgets from Dojo's @dojo/widgets library, a third-party provider, or any that may be developed in-house for a particular application.

Feature	Description
Per-widget stylesheets	CSS Modules can be used to define stylesheets that are scoped to individual widgets, avoiding potential cross-contamination and style name clashes. A widget can refer to its exact CSS class names via typed CSS module imports and IDE autocompletion.
Robust theming support	Themeable widgets can easily be developed that allow for simplified and centralized whole-application theming, as well as single-instance, targeted style tweaking and overriding, if required. CLI tooling is available to support distributing custom themes.
Reactive theme change response	Similar to other reactive state changes within a Dojo application, only the affected widgets will be re-rendered when a theme change is made at either a widget level or across an entire application.
Abstracted CSS properties	Individual CSS modules can refer to a set of centrally-defined `:root` style variables through CSS custom properties and `var()`.
Simplified third-party widget theming	Applications can easily extend their themes to cover third-party widgets, such as those from Dojo's native widget library, and Dojo also provides out-the-box themes which applications can base their own on. CLI tooling is available to streamline theme creation and composition.

Basic usage

Note: The following examples build upon each other in a linear order. Individual examples are kept brief to only highlight relevant changes from any previous examples.

These examples assume an application with the following name:

package.json

{
    "name": "my-app"
}

The application name becomes relevant when specifying widget theme keys.

Defining a CSS module for a widget
Using the corresponding typed style classes within the widget's TypeScript code

src/styles/MyWidget.m.css

.root {
    font-family: sans-serif;
}

src/widgets/MyWidget.tsx

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.root]}>My Widget</div>;
});

Inject the theme middleware
Using theme.classes to return the themed css class name, which allows a widget's default styles to be overridden by a theme

src/widgets/MyWidget.tsx

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

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

const factory = create({ theme });

export default factory(function MyWidget({ middleware: { theme } }) {
    const { root } = theme.classes(css);
    return <div classes={[root]}>My Widget</div>;
});

Creating a theme

Overriding a widget's default CSS class with custom theme style properties
Linking one or more overrides via the appropriate widget theme keys into a theme structure

src/themes/MyTheme/MyWidget.m.css

.root {
    color: hotpink;
    background-color: slategray;
}

src/themes/MyTheme/theme.ts

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

export default {
    'my-app/MyWidget': myWidgetCss
};

Abstracting common theme properties

Importing a central variables.css regular CSS file that defines CSS custom properties
Referring to the custom properties via var()

src/themes/variables.css

:root {
    --foreground: hotpink;
    --background: slategray;
}

src/themes/MyTheme/MyWidget.m.css

@import '../variables.css';

.root {
    color: var(--foreground);
    background-color: var(--background);
}

Specifying a default application theme

The theme middleware can be used to set the application theme. To set a "default" or initial theme, the theme.set function can be used with the theme.get function to determine if the theme needs to be set. Setting the default theme should be done in the application's top level widget.

src/App.tsx

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

import myTheme from '../themes/MyTheme/theme';

const factory = create({ theme });

export default factory(function App({ middleware: { theme }}) {
    // if the theme isn't set, set the default theme
    if (!theme.get()) {
        theme.set(myTheme);
    }
    return (
        // the application's widgets
    );
});

Note: When using both function-based and class-based widgets, the theme needs to be registered with the application registry. This is true when using any class-based widget dependencies such as @dojo/widgets. Please see the class-based theming section for more details.

Changing the theme within an application

Using the theme middleware to allow users to choose between available themes

src/widgets/ThemeSwitcher.tsx

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

import myTheme from '../themes/MyTheme/theme';
import alternativeTheme from '../themes/MyAlternativeTheme/theme';

const factory = create({ theme });

export default factory(function ThemeSwitcher({ middleware: { theme } }) {
    return (
        <div>
            <button
                onclick={() => {
                    theme.set(myTheme);
                }}
            >
                Use Default Theme
            </button>
            <button
                onclick={() => {
                    theme.set(alternativeTheme);
                }}
            >
                Use Alternative Theme
            </button>
        </div>
    );
});