GUIDE

Concepts

The model behind every dj-* component: four ideas that explain almost everything else in the docs.

1. 1Custom elements

   Every dj-* tag is a standard Web Component: a real HTML element registered through the Custom Elements v1 API, not a framework-specific wrapper. That is what makes the same <dj-button> work identically in React, Vue, Angular, Svelte, or no framework at all. The browser itself knows what it is.

2. 2Shadow DOM

   Each component keeps its own markup and styles inside a shadow root. Your page's CSS cannot leak in and break it, and the component's internal styles cannot leak out. Styling reaches in only through --dj-* custom properties and documented ::part() selectors, never by fighting specificity.

3. 3Token theming (--dj-*)

   Color, spacing, type, and radii are all CSS custom properties, layered primitives → semantic roles → component tokens. Override a primitive and everything built on it follows. Override one component token for a narrow, targeted tweak. The theming guide covers switching themes, brand overrides, and scoped themes.

   --dj-color-primary-600: #2563EB;
   --dj-color-text: var(--dj-color-neutral-800);

4. 4No-bundler ESM + import maps

   Every @dojo-ng/* package ships as plain ES modules, so no build step is required. Install only the packages you use, such as @dojo-ng/button or @dojo-ng/data-grid, and register each with a bare specifier in an import map. The page then loads them straight from a CDN. A bundler such as Vite reads the same packages from node_modules just as well.

   <script type="importmap">
   {
     "imports": {
       "@dojo-ng/button": "https://esm.sh/@dojo-ng/button",
       "@dojo-ng/data-grid": "https://esm.sh/@dojo-ng/data-grid"
     }
   }
   </script>

   esm.sh resolves each package's own imports for you. A map you write by hand against node_modules needs an entry for those dependencies too: Lit, and shared packages such as @dojo-ng/dojo-element.