MIGRATE
Why web components
A framework-native component library is written for one framework. A web component library is written for the browser. This page compares the two, including where the framework-native kind is the better choice.
| Framework-native library | Web components (Dojo NG) | |
|---|---|---|
| Where it runs | One framework. | Any framework that renders DOM, and plain HTML with no framework. |
| When the framework changes | The component library is rebuilt with the app. | The same components move to the new framework. |
| Styling | Depends on the library's CSS approach. Page CSS can reach anything. | Shadow DOM isolates each component. You style through --dj-* tokens and ::part(). |
| Forms | Works with that framework's form libraries. | Controls join native <form> elements: FormData, validation, and reset. Framework form libraries may need an adapter, and Dojo NG does not ship any yet. |
| API style | Idiomatic for the framework: its props, events, and types. | DOM properties, attributes, and events. Most frameworks bind these directly; React 19 needs a ref for custom events. |
| Server-side rendering | Usually mature. | Not available in Dojo NG yet. Components render in the browser. |
When a framework-native library is the better choice
If your organization uses one framework, plans to stay on it, and needs server-side rendering today, a library written for that framework will fit more naturally. Its components feel like the rest of your code, its types come from the framework, and its server-rendering story is likely complete. Web components ask you to accept a few seams in exchange for portability, and if you never need the portability, the seams are a cost with no return.
When web components fit
The case gets strong when more than one framework is involved, now or later:
- Your company runs React in one product and Angular or Vue in another, and wants one component set and one look across them.
- A design-system team serves several product teams that do not share a framework.
- The application needs to outlive the framework it is written in today.
- You are in the middle of a framework migration and do not want to rebuild the component library twice.
- Part of the application is server-rendered pages with little or no framework, and those pages need the same controls as the rest.
Moving over one screen at a time
A dj-* element is a standard HTML element, so it can sit next to the components you use today. You do not have to convert an application all at once. Start with one screen, or one control type such as buttons or date inputs, and replace the old components as you touch that code.
During a framework migration this works in your favor. A dj-select placed in an Angular screen today renders and behaves the same after that screen is rewritten in React, so the component layer is finished before the framework move is.
To theme the new components to match your existing design while both kinds share the page, override the primary color scale and a few semantic tokens. The theming guide shows how.
Guides for specific libraries
Guides that map MUI, Ant Design, and PrimeNG components to dj-* elements, prop by prop, are planned. They wait until the Dojo NG API settles. Every package is still pre-1.0, and a mapping to an API that may change would mislead you.
Until then, the component catalog lists everything that ships, and each component's README on npm documents its properties, events, slots, and parts. The launch post explains why Dojo NG is built this way.
dj-* component in React, Vue, Angular, Svelte, or plain HTML.