Introduction

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 , a third-party provider, or any that may be developed in-house for a particular application.

Basic usage

These examples assume an application with the following name:

package.json

The application name becomes relevant when specifying .

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

.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>;
});

Making a widget themeable

• 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

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 } }) {
    return <div classes={[root]}>My Widget</div>;
});

• Set the theme.variant class on the widget’s root.
• css-properties get applied at the correct DOM level and do not leak out of the widget’s DOM.

src/widgets/MyWidget.tsx

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

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
};

• Placing theme variables into a variant module as CSS custom properties
• Referring to the custom properties via var()
• Not relying on local variables or a common variables.css file.

/* single root class */
.root {
    --foreground: hotpink;
    --background: slategray;
}

src/themes/MyTheme/MyWidget.m.css

src/themes/MyTheme/index.tsx

import * as defaultVariant from './variants/default.m.css';
import * as myWidgetCss from './MyWidget.m.css';
export default {
    theme: {
        'my-app/MyWidget': myWidgetCss
    },
    variants: {
        default: defaultVariant
    }

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.

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, 'variant-name');
    }
    return (
        // the application's widgets
    );

Changing the theme within an application

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