Working with themes

The theme key for a given widget is determined as:

where package-name is the value of the name property within the project’s package.json, and widget-css-module-name is the filename of the primary CSS module used for the widget (without the .m.css extension).

For a given project:

{
    "name": "my-app"
}

When following widget CSS module naming conventions, a given widget such as src/widgets/MyWidget.ts will use a corresponding CSS module name similar to src/styles/MyWidget.m.css. The theme key for MyWidget is therefore:

my-app/MyWidget

Here, the name of the widget is the same as the the name of its CSS module file, but developers should be careful not to mistake the widget’s theme key as representing the widget’s TypeScript class name.

For a second widget that does not follow CSS module naming conventions, such as src/widgets/BespokeWidget.ts that uses a corresponding CSS module such as src/styles/BespokeStyleSheet.m.css, its widget theme key would instead be:

my-app/BespokeStyleSheet

Themes are TypeScript modules that export a default object which maps to typed CSS module imports. CSS modules in a theme are the same as regular modules used directly in widgets. Once a theme is applied in an application, each widget identified via its theme key in the theme’s definition object will have its styles overridden with those specified in the CSS module associated with that widget’s theme key.

The following is a simple illustration of a complete theme for a single MyWidget widget (using a default CSS module of MyWidget.m.css), contained in a project named my-app:

.root {
    color: blue;
}

Here, MyWidget is following naming conventions with its primary style class being named root, allowing myTheme to easily override it via the root class in its src/themes/myTheme/styles/MyWidget.m.css CSS module.

The theme associates the new styling class to MyWidget via its . When myTheme is applied, MyWidget will have its color set to blue and will no longer receive any other styles defined in the root class in its original CSS module.

It is likely that application themes will need to include styling of any third-party widgets that may be used, such as those provided by Dojo’s native widget library.

The package provides tooling support to quickly generate theme scaffolding for third party widgets, via its dojo create theme CLI command. It can be installed locally within an application via:

and can be used as follows from a project’s root directory:

dojo create theme -n {myThemeName}

Running this command will begin to create the specified myThemeName theme by asking two questions:

What Package to do you want to theme?
- The answer to this should be all the packages that contain the third-party widgets intended for theming, for example @dojo/widgets. The command will continue to ask for more packages until a user is done.
Which of the {third-party-package} theme files would you like to scaffold?
- A list will be shown of all themeable widgets in the third-party packages that were specified when answering the first question. Users can then pick the subset of all compatible widgets that should be included in the resulting theme - usually only the widgets that are actually used in the current application will be selected, to help keep the theme’s size to a minimum.

Several files will be created in the current project upon successful execution of the command:

src/themes/{myThemeName}/theme.ts
src/themes/{myThemeName}/{third-party-package}/path/to/{selectedWidget}.m.css

The theme’s CSS modules created for all {selectedWidget}s come ready with themeable CSS selectors which can then be filled in with the appropriate stylings for {myThemeName}.

Compatible packages

Any third-party package that has a theme directory containing widget CSS module files (*.m.css) and their corresponding compiled definition files () is compatible.

For example:

node_modules
└── {third-party-package}
    └── theme
        │   {widget}.m.css
        │   {widget}.m.css.js

Note that when using dojo create theme to scaffold a new theme, there is no need to use dojo build theme, as all relevant files will already be in place. This applies to themes in projects that are built either via or .

To use the tooling, install @dojo/cli-build-theme locally in a theme project:

npm install --save-dev @dojo/cli-build-theme

Then to build a theme, run the command and specify a theme name as well as an optional release version:

If no release is specified, then the current version from package.json will be used instead.

Running the command will create a new dist/src/{myThemeName} directory in the project containing:

A primary that can be imported and used to theme an application or compatible widgets
All widget CSS module .m.css files contained in the theme. These files can be referenced directly via for any applications deriving their own theme off the newly-built one.
An index.css file that should be imported into an application’s main.css, if using the theme in its entirety.
Extra files supporting :
- A {name}-{release}.js file that registers the theme with a global registry (added via a <script> tag).
- A {name}-{release}.css file that is added via a <link rel="stylesheet"> tag.

The @dojo/themes package provides a collection of ready-to-use themes that cover all widgets in Dojo’s . The themes can be used as-is, or composed as the basis for a full application theme.

To use the themes, install @dojo/themes into your project, for example through npm i @dojo/themes. Then, for regular Dojo applications:
Import the theme CSS into your project’s main.css:
```
@import '~@dojo/themes/dojo/index.css';
```

Import the theme TypeScript module and use it :

import theme from '@dojo/themes/dojo';
render() {
    return w(Button, { theme }, [ 'Hello World' ]);
}

If attempting to use the themes in custom elements, after installing @dojo/themes:

<link rel="stylesheet" href="node_modules/@dojo/themes/dojo/dojo-{version}.css" />