Frequently Asked Questions

Why Don't Components Display with Self-Closing Tags?

mdui is a library based on Web Components. Web Components do not support self-closing tags, so you should always use closing tags with mdui components.

<!-- Incorrect usage -->
<mdui-text-field/>

<!-- Correct usage -->
<mdui-text-field></mdui-text-field>

How to Prevent Unstyled Components Display Before Loading?

mdui components are registered via JavaScript, which may cause a brief unstyled display until the JavaScript loads and registers the components. Here are two solutions:

One solution is to use the :defined pseudo-class to hide unregistered mdui components. The following CSS hides all unregistered mdui components and shows them once registered:

:not(:defined) {
  visibility: hidden;
}

Another solution is to use the customElements.whenDefined() method. This method returns a promise that resolves when the specified component is registered. To handle cases where some components may fail to load, use Promise.allSettled().

In the following example, the <body> element is initially hidden using opacity: 0 and fades in after the components are registered. Promise.allSettled() is used to wait for all promises to complete, ensuring the page displays properly even if a component fails to load.

<style>
  body {
    opacity: 0;
  }

  body.ready {
    opacity: 1;
    transition: 0.25s opacity;
  }
</style>

<script type="module">
  await Promise.allSettled([
    customElements.whenDefined('mdui-button'),
    customElements.whenDefined('mdui-card'),
    customElements.whenDefined('mdui-checkbox')
  ]);

  // After registering the button, card, and checkbox components, add the 'ready' class to fade in the page
  document.body.classList.add('ready');
</script>
MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Introduction Installation Usage TypeScript Support IDE Support Localization Frequently Asked Questions
Styles
Dark Theme Dynamic Theme Typography Design Tokens
Frameworks
React Vue Angular
Components
Button ButtonIcon Fab SegmentedButton Chip Card Checkbox Radio Switch Slider RangeSlider List Collapse Tabs Dropdown Menu Select TextField LinearProgress CircularProgress Dialog Divider Avatar Badge Icon Tooltip Snackbar NavigationBar NavigationDrawer NavigationRail BottomAppBar TopAppBar Layout
Functions
JavaScript Library dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
Libraries
@mdui/icons