Resolving MGT Custom Element Conflicts via Disambiguation

Question

My SPFx web part fails to render when another component on the page uses a different version of the Microsoft Graph Toolkit (MGT). This triggers a global namespace collision, specifically the Duplicate definition error, because both versions attempt to register identical custom element tags in the browser's customElements registry.

How can I fix it ? Is it a known limitation?

Answer 1

Hello Gerwin Van de Lurg

Thank you for reaching Q&A Forum.

Based on the official Microsoft documentation: Microsoft Graph Toolkit component disambiguation , any attempt to register a component using a previously registered tag name results in an error when calling CustomElementRegistry.define()

Because Microsoft Graph Toolkit (MGT) components are implemented as Web Components and registered globally in the browser, this is expected behavior when multiple SPFx components on the same page load different versions of MGT. In this scenario, each version attempts to register the same custom element tag names again, which leads to a “Duplicate definition” error and causes the web part to fail rendering.

Microsoft provides a disambiguation feature to mitigate this issue. With disambiguation, you can specify a unique string that is added to the tag name of all MGT components used by your application. The supplied value is inserted as the second segment of the tag name. For example, when using customElementHelper.withDisambiguation('foo'), the <mgt-login> tag is referenced as <mgt-foo-login>. This prevents naming collisions and allows multiple MGT-based solutions to coexist on the same page.
Please note that the disambiguation string is automatically converted to lowercase by the helper method, and a console warning is logged if uppercase characters are provided. However, the input is not fully sanitized, so using invalid characters may still trigger a DOMException during component registration.

In SPFx scenarios specifically, it is important to ensure that disambiguation is configured early in the lifecycle (for example, in the web part’s onInit method). Additionally, using lazy loading for React components is recommended to avoid situations where module import hoisting causes components to be registered before disambiguation is applied.

I hope this information is helpful. Please let me know if you have any further questions.

---

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.