Install maz-ui with Vue

Maz-UI is a Vue.js UI library that provides a set of pre-built components, plugins, directives and utilities to help you build modern, responsive, and accessible web applications.

Model Context Protocol (MCP)

A MCP server is available to connect your IA agents to the documentation and implement Maz-UI easily.

Check out the documentation of @maz-ui/mcp

Quick Start

Installation

pnpm

pnpm add maz-ui @maz-ui/themes

npm

npm install maz-ui @maz-ui/themes

yarn

yarn add maz-ui @maz-ui/themes

Install plugin

import { MazUi } from 'maz-ui/plugins/maz-ui'

import { mazUi } from '@maz-ui/themes'
import { en } from '@maz-ui/translations/locales'

import 'maz-ui/styles'

app.use(MazUi, {
  theme: {
    preset: mazUi,
  },
  translations: {
    messages: { en },
  },
})

Why provide preset and messages?

• preset -- Providing the theme preset synchronously avoids FOUC (Flash of Unstyled Content). Without it, components render without their CSS variables until the theme loads.
• messages -- By default, Maz-UI does not bundle any translations. If you don't provide messages for the current locale, components will briefly show raw translation keys instead of actual text until the async loading completes.

Advanced Integration

You must the MazUi plugin to initialize the theme and translations.

• Theme documentation
• Translations documentation

import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi } from '@maz-ui/themes/presets'
import { fr } from '@maz-ui/translations/locales'
// or import fr from '@maz-ui/translations/locales/fr'

// Import Maz-UI styles before your own CSS
import 'maz-ui/styles'
import './style.css'

app.use(MazUi, {
  /**
   * Theme configuration (optional if you are using the default theme)
   * More information in dedicated documentation
   * @see https://maz-ui.com/guide/themes
   */
  theme: {
    preset: mazUi, // 'ocean' | 'pristine' | 'obsidian'
    overrides: {
      foundation: {
        'radius': '0.7rem',
        'border-width': '0.0625rem',
      },
      colors: {
        light: {
          primary: '220 100% 50%',
        }
      }
    }
  },
  /**
   * Translations configuration (optional if you are using english)
   * More information in dedicated documentation
   * @see https://maz-ui.com/guide/translations
   */
  translations: {
    locale: 'fr',
    fallbackLocale: 'en',
    messages: {
      fr,
    },
  },
})

app.mount('#app')

Alternative: MazUiProvider

If Maz-UI is only used on specific pages, you can use the MazUiProvider component instead of the plugin to keep Maz-UI out of your entry bundle.

Using your first component

Let's start with a simple button to see Maz-UI in action:

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

function handleClick() {
  console.log('Button clicked!')
}
</script>

<template>
  <MazBtn color="primary" @click="handleClick">
    Hello Maz-UI! 👋
  </MazBtn>
</template>

Theming

More information in the theme documentation.

Translations

More information in the translations documentation.

Plugins

More information about installation and usage in:

• aos (animations on scroll)
• dialog (display modales without any implementation in template)
• toast (display notifications)
• wait (display loading states)

Directives

More information about installation and usage in:

• tooltip (display tooltips)
• click-outside (detect outside clicks)
• lazy-img (lazy load images)
• zoom-img (zoom images on click)
• fullscreen-img (display images fullscreen on click with an animate effect)

Smart Loading with resolvers

Installation

pnpm

pnpm add unplugin-vue-components unplugin-auto-import

npm

npm install unplugin-vue-components unplugin-auto-import

yarn

yarn add unplugin-vue-components unplugin-auto-import

For the ultimate developer experience, use auto-imports for components, composables, and directives.

Into your vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import {
  MazComponentsResolver,
  MazDirectivesResolver,
  MazModulesResolver
} from 'maz-ui/resolvers'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'


export default defineConfig({
  plugins: [
    vue(),
    // Auto-import components
    Components({
      resolvers: [
        MazComponentsResolver(),
        MazDirectivesResolver(),
      ],
      dts: true,
    }),
    // Auto-import composables and utilities
    AutoImport({
      resolvers: [MazModulesResolver()],
      dts: true,
    }),
  ],
})

Now use everything without imports:

<script setup lang="ts">
// Auto-imported composables and utilities
const text = ref('')
const toast = useToast()

// Auto-imported utility functions
const debouncedSearch = debounce((query) => {
  console.log('Searching:', query)
}, 300)

function handleClickOutside() {
  toast.info('Clicked outside!')
}
</script>

<template>
  <!-- Auto-imported components -->
  <MazBtn>Button</MazBtn>
  <MazInput v-model="text" placeholder="Type here..." />

  <!-- Auto-imported directives -->
  <div v-click-outside="handleClickOutside">
    Click outside detector
  </div>

  <!-- Auto-imported tooltip directive -->
  <MazBtn v-tooltip="'This is a tooltip'">
    Hover me
  </MazBtn>
</template>

Available Resolvers

Resolver	Purpose	Import
MazComponentsResolver	Components (MazBtn, MazInput, etc.)	'maz-ui/resolvers'
MazDirectivesResolver	Directives (v-click-outside, v-tooltip, etc.)	'maz-ui/resolvers'
MazModulesResolver	Composables & utilities (useToast, debounce, etc.)	'maz-ui/resolvers'

Avoiding Naming Conflicts

To avoid naming conflicts, you can use the prefix option:

export default defineConfig({
  plugins: [
    Components({
      resolvers: [
        MazComponentsResolver(),
        MazDirectivesResolver({ prefix: 'Maz' }), // v-maz-tooltip
      ],
    }),
    AutoImport({
      resolvers: [
        MazModulesResolver({ prefix: 'Maz' }), // useMazToast, useMazTheme
      ],
    }),
  ],
})

Complete Resolver Documentation

For comprehensive resolver configuration, advanced options, real-world examples, and troubleshooting, check out our dedicated resolver guide.