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:

    1. {
    2.     "name": "my-app"
    3. }

    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:

    1. 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:

    1. 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:

    1. .root {
    2.     color: blue;
    3. }

    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.

    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 .

    The @dojo/cli-create-theme 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:

    1. npm install --save-dev @dojo/cli-create-theme

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

    1. dojo create theme -n {myThemeName}

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

    • 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}.

    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:

    1. node_modules
    2. └── {third-party-package}
    3.     └── theme
    4.         │   {widget}.m.css
    5.         │   {widget}.m.css.js

    Dojo’s cli-build-theme package provides a CLI command to help build themes that are intended for distribution across multiple applications. It will create all files necessary to .

    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 @dojo/cli-build-widget.

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

    1. 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:

    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 directory containing all fonts and images included within the theme’s directory.
    • 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.

    1. Import the theme CSS into your project’s main.css:

      1. @import '~@dojo/themes/dojo/index.css';

    2. Import the theme TypeScript module and use it :

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

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

    1. Add the custom element-specific theme CSS to index.html:

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

    2. Add the custom element-specific theme JS to index.html:

      1. <script src="node_modules/@dojo/themes/dojo/dojo-{version}.js"></script>

    Once @dojo/themes is installed in a project, it can be used as the basis for an extended application theme by including relevant components with CSS modules’ composes functionality in the new theme.

    @dojo/themes also includes its own which can be imported if the extended application theme would like to reference Dojo-specified properties elsewhere in the new theme.

    The following is an example of a new theme for the @dojo/widgets/button widget that extends off @dojo/themes, and changes the button’s background to green while retaining all other button theme style properties:

    1. @import '@dojo/themes/dojo/variables.css';
    3. .root {
    4.     composes: root from '@dojo/themes/dojo/button.m.css';
    6. }