Dojo FAQ: How can I create a Dijit theme?

By on April 30, 2014 11:40 am


Dojo includes an extensive collection of layout and data widgets in the Dijit package, all of which are built with support for internationalization (i18n) and accessibility (a11y). Dijit includes four themes to customize the appearance of Dijit widgets:

Claro Theme in the Dijit Theme Tester

Claro Theme in the Dijit Theme Tester

Dijit’s Claro theme is built with the LESS CSS preprocessor. We highly recommend using a preprocessor to facilitate modularity and improve code reuse. At SitePen we prefer Stylus since it is capable of remapping URL paths used in imported files, which is important for creating modular CSS. With its excellent support for mixins and the nib CSS3 extensions, Stylus is valuable tool for CSS development.

Switching from LESS to Stylus is relatively straightforward, and we provide the dijit-claro-stylus package to ease the transition.

Creating Your Own Theme

If you are generally happy with one of the existing themes and just looking to alter it a bit you can simply override the relevant selectors with your custom rules. The best way to see what rules are applied to an element is to use your browser’s developer tools to inspect the element and see which selectors are in effect. If you use the same selector with different rules in a CSS file that is loaded after Dijit’s CSS then your rules will take effect.

If you want to make more extensive changes, but not start from scratch, you can start with an existing theme, make a copy of it, and edit it. This allows you to leverage the significant work that has already been done to create the theme, but this approach can make some changes difficult due to the need to override the many rules already defined in the theme. If you want a completely custom design you can look at the source of existing themes for reference and define your own theme from scratch. In this case you will still probably want to include dijit/themes/dijit.css as it contains layout rules that give Dijits their basic structural properties. Or even better would be to start with the dijit-claro-stylus package.

Dijit loads Dojo’s dojo/uacss module which applies user agent-specific classes to the HTML document, e.g dj_ie, dj_chrome, dj_firefox. It will also apply class names to indicate quirks mode rendering and the box model. These can be useful in creating themes that work on a variety of web browsers.


  • Follow Claro’s file structure: create a single top-level .css theme file that will be included in your application’s HTML and use @import statements to load CSS files with rules for individual widgets
    • Dojo’s build tool works well with this structure and will create a single CSS file to minimize HTTP requests
  • Pay attention to stateful rules – in order to support older browsers (which lack robust support for selectors like :hover, :focus, etc.), Dijit uses the _CssStateMixin module to apply UI state classes like hover, focus, and selected to elements
  • Use the least-specific selector that will work
  • Avoid id selectors and the !important keyword
  • Test in all browsers you want to support
    • Dijit supports a wide range of browsers, which in some cases involves browser-specific rules that may not work the same with your custom rules across all browsers

Bootstrap for Dojo

Martin Pengelly-Phillips has created a Dijit theme based on the popular Bootstrap framework – dbootstrap. This is a great theme that is ready to use with Dijit, or you can look at the source for ideas on creating a Dijit theme using Stylus.


dboostrap theme

Learning More

We cover theming, UI design, custom widget development, and more in our Dojo workshops offered throughout the US, Canada, and Europe, or at your location. We also provide expert JavaScript & Dojo support and development services to help you with creating custom themes and other JavaScript and Dojo development efforts.