How to lazy load Maz UI?

[jacobg]

Our SPA uses Prime Vue as the main UI framework. We use Maz UI's phone number input, which is amazing and the best out there!

In v3, we can just import/bootstrap Maz UI in the form components that use the phone number input, and the vite bundler will automatically lazily dynamically load the Maz UI code just-in-time.

In v4, Maz UI seems to want to be bootstrapped into the Vue application right away. How can we delay that and just lazy load in the components where it's needed?

Thanks very much.

[LouisMazel]

Hi @jacobg,

Thanks for the kind words about MazInputPhoneNumber!

I think this is actually a misunderstanding about what app.use(MazUi, {...}) does.

The plugin does not register components

The app.use(MazUi, {...}) call only injects theming and translations via Vue's provide/inject. It does not register any component globally. It's very lightweight — no component code is loaded at this step.

// main.ts — this is just theme + translations setup, nothing heavy
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi } from '@maz-ui/themes'
import { en } from '@maz-ui/translations'
import 'maz-ui/styles'

app.use(MazUi, {
  theme: { preset: mazUi },
  translation: { locale: 'en', messages: { en } }
})

This is required because MazInputPhoneNumber internally uses useTranslations(), which relies on this setup and consumes CSS variable tokens.

Components are individually importable and tree-shakeable

Just like in v3, you import only the components you need. Vite will tree-shake everything else — you're not loading the entire Maz UI library:

<script setup lang="ts">
import MazInputPhoneNumber from 'maz-ui/components/MazInputPhoneNumber'

const phoneNumber = ref('')
</script>

<template>
  <MazInputPhoneNumber v-model="phoneNumber" />
</template>

Only MazInputPhoneNumber and its dependencies (like libphonenumber-js) end up in your bundle — nothing else from Maz UI.

Bonus: true lazy loading with defineAsyncComponent

If you want to go further and defer the download until the component is actually rendered (e.g. the form is not visible on initial page load), you can use defineAsyncComponent:

<script setup lang="ts">
import { defineAsyncComponent } from 'vue'

const MazInputPhoneNumber = defineAsyncComponent(
  () => import('maz-ui/components/MazInputPhoneNumber')
)
</script>

This way, the component code + libphonenumber-js are only downloaded when the component is rendered for the first time. Combine this with route-level
lazy loading for even better results:

const routes = [
  {
    path: '/contact',
    component: () => import('./pages/ContactForm.vue'),
  },
]

app.use() is only for lightweight theme/translation injection — no components are loaded. Individual imports are tree-shakeable (same as v3). For deferred loading, use defineAsyncComponent.

[jacobg]

Thank you @LouisMazel for the explanation. Are you saying the Vue.use bootstrap is still necessary with defineAsyncComponent? I think so, as it seems orthogonal. The component part I think is ok, because the routes are already loaded via async. But I'm still hoping to be able to move the maz ui bootstrap stuff to the specific component that uses the phone number input. It doesn't get used so often, and the benefits of keeping it out of main.js are: (1) cleaner app bootstrapping; and (2) there is still maz ui bootstrap code that needs to get loaded. Would it be possible to support an alternative lazy approach not at vue app creation time? Thanks again!

[LouisMazel]

Hi @jacobg,

To answer your question directly: yes, installing the plugin in main.js is currently required, even if you lazy load all your components with defineAsyncComponent. The theme and translations are injected via Vue's provide/inject system, and the MazInputPhoneNumber component will throw an error if the plugin isn't installed.

I understand your use case, actually. You want zero Maz UI footprint in your main bundle until a component actually needs it.

I'm going to develop something like a <MazUiProvider> component to address this. The idea is simple: instead of calling app.use(MazUi, {...}) globally in main.js, you'd wrap your Maz UI components in a provider that handles the theme and translations setup locally in its subtree:

<script setup lang="ts">
import { mazUi } from '@maz-ui/theme/presets'
</script>

<template>
  <MazUiProvider :theme="{ preset: mazUi }" :translations="{ locale: 'en' }">
    <MazInputPhoneNumber v-model="phone" />
  </MazUiProvider>
</template>

This way, nothing related to Maz UI would be in your main.js and in your bundle entry, everything gets loaded only with the pages that need it.

This won't be available immediately, but it's on my radar. I'll keep this discussion updated.

What do you think about it? Sound good for you?

[jacobg]

@LouisMazel wow amazing! That's would be so awesome! Thanks so much!!

[LouisMazel]

@jacobg

You can already test or migrate to the new MazUiProvider component, I released a beta version v4.7.0-beta.0.

Let me know if you need documentation (https://github.com/LouisMazel/maz-ui/blob/develop/apps/docs/src/guide/maz-ui-provider.md) and if the solution is working for you!

If all is good for you, I will release it in a stable version.

[jacobg]

@LouisMazel Amazing! I'll try beta.1 soon. Thanks!

Regarding my setup, I was upgrading from v3 so there was no maz ui in main.ts. And no nuxt, front-end only. I was able to resolve the translation warnings by specifying translations prop like this:

<MazUiProvider :theme="{ preset: mazUi, mode: 'light' }" :translations="{ locale: 'en', messages: { en } }">

But without the translations prop, those warnings show.

[LouisMazel]

Oh yes, obviously!

It's because by default, MazUiProvider (like MazUi plugin) doesn't load any languages (messages) to avoid unused messages in the final bundle. But if no messages are provided, I will load the English messages with a promise. So the messages are not immediately available. I mentioned it here: https://maz-ui.com/guide/translations#basic-usage (in the warning area)

It's the same logic for the theme preset. By default, any preset is loaded. If no preset is provided, I will load the mazUi preset asynchronously.

So you have to provide the messages of the language and the preset you want to use (at least the ones you want to use immediately). This is a complete example :

<MazUiProvider
  :theme="{
    preset: mazUi,
    colorMode: 'auto',
    darkClass: 'dark',
    darkModeStrategy: 'class',
    mode: 'both',
    strategy: 'hybrid',
    overrides: {
      colors: {
        light: {
          primary: '272 99% 54%',
          destructive: '357 96% 58%',
        },
      },
    },
  }"
  :translations="{
    locale: 'fr',
    fallbackLocale: 'en',
    preloadFallback: false,
    messages: {
      fr,
    },
  }"
>
    ...
</MazUiProvider>

The only required data are : theme: { preset: mazUi } and translations: { locale: 'en' messages: { en: en } (obviously, you can change the values)

I'm sorry, the example in my previous message is incorrect.

I will improve the types of theme and translations props, and the documentation pages.

[LouisMazel]

New beta released with the new strict types: https://github.com/LouisMazel/maz-ui/releases/tag/v4.7.0-beta.2

[jacobg]

@LouisMazel Amazing! I'd say 4.7 is ready for mainstream release! 😄 🚀

[LouisMazel]

Peeeerfect ! I publish the new stable version !

Thank you so much for your very helpful feedback!

[LouisMazel]

@jacobg

It's released in v4.7.0.

Enjoy!

[jacobg]

Woo hoo! Thank you @LouisMazel ! 🥳 🚀