Summary Maz-UI v4 - Modern Vue & Nuxt component library with 50+ standalone components, composables, directives, theming, i18n, and SSR support. Use when building Vue/Nuxt applications with forms, dialogs, tables, animations, or need responsive design system with dark mode.
Maz-UI v4 - Vue & Nuxt Component Library
Maz-UI is a comprehensive, standalone component library for Vue 3 and Nuxt 3 applications, offering 50+ production-ready components, powerful theming, internationalization, and exceptional developer experience.
Latest Version : 4.9.3 (as of 2026-08-03)
Package : maz-ui | @maz-ui/nuxt | @maz-ui/themes | @maz-ui/translations | @maz-ui/icons
Quick Start
Vue 3 Installation
# Install core packages
pnpm add maz-ui @maz-ui/themes
# Or with npm
npm install maz-ui @maz-ui/themes
Setup in main.ts:
import { createApp } from 'vue'
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi } from '@maz-ui/themes'
import { en } from '@maz-ui/translations'
import 'maz-ui/styles'
import App from './App.vue'
const app = createApp(App)
app.use(MazUi, {
theme: { preset: mazUi },
translations: { messages: { en } }
})
app.mount('#app')
Use Components :
<script setup>
import MazBtn from 'maz-ui/components/MazBtn'
import MazInput from 'maz-ui/components/MazInput'
import { ref } from 'vue'
const inputValue = ref('')
</script>
<template>
<MazInput v-model="inputValue" label="Name" />
<MazBtn color="primary">Submit</MazBtn>
</template>
Nuxt 3 Installation
# Install Nuxt module
pnpm add @maz-ui/nuxt
Setup in nuxt.config.ts:
export default defineNuxtConfig({
modules: ['@maz-ui/nuxt']
// That's it! Auto-imports enabled 🎉
})
Use Components
<script setup>
// Auto-imported composables
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>
<template>
<!-- Auto-imported components -->
<MazInput v-model="inputValue" label="Name" />
<MazBtn color="primary" @click="toast.success('Submitted!')">
Submit
</MazBtn>
</template>
Core Capabilities
🎨 Components (50+)
MazInput - Text input with validation statesMazSelect - Dropdown selectMazTextarea - Multi-line text inputMazCheckbox - Checkbox with labelMazRadio - Radio buttonsMazSwitch - Toggle switchMazSlider - Range sliderMazInputPhoneNumber - International phone input with validationMazInputCode - Code/PIN inputMazInputPrice - Currency input with formattingMazInputTags - Tag/chip inputMazDatePicker - Date pickerMazChecklist - Searchable checklist
MazBtn - Button with variantsMazCard - Container cardMazBadge - Label badgeMazAvatar - User avatarMazIcon - Icon displayMazSpinner - Loading spinnerMazTable - Data table with sorting/paginationMazTabs - Tab navigationMazStepper - Step indicatorMazPagination - Pagination controls
MazDialog - Modal dialogMazDialogConfirm - Confirmation dialogMazDrawer - Slide-out drawerMazBottomSheet - Mobile bottom sheetMazBackdrop - Overlay backdropMazPopover - Floating popoverMazDropdown - Dropdown menu
MazFullscreenLoader - Loading overlayMazLoadingBar - Progress barMazCircularProgressBar - Circular progressMazReadingProgressBar - Reading progress indicatorMazAnimatedText - Text animationsMazAnimatedElement - Element animationsMazAnimatedCounter - Number counter animationMazCardSpotlight - Card with spotlight effect
MazCarousel - Image carouselMazGallery - Image galleryMazAccordion - Collapsible panelsMazExpandAnimation - Expand/collapse animationMazLazyImg - Lazy-loaded imageMazPullToRefresh - Pull-to-refresh gestureMazChart - Chart.js integration
🔧 Composables (14+)
useTheme() - Theme and dark mode management
useTranslations() - i18n management
useToast() - Toast notificationsuseDialog() - Programmatic dialogsuseWait() - Loading states
useBreakpoints() - Responsive breakpointsuseWindowSize() - Window dimensionsuseTimer() - Timer/countdownuseFormValidator() - Form validation (Valibot)useIdleTimeout() - Idle detectionuseUserVisibility() - Page visibilityuseSwipe() - Swipe gesturesuseReadingTime() - Reading time calculationuseStringMatching() - String utilitiesuseDisplayNames() - Localized display names
📌 Directives (5)
v-tooltip - Tooltipsv-click-outside - Outside click detectionv-lazy-img - Lazy loadingv-zoom-img - Image zoomv-fullscreen-img - Fullscreen image viewer
🔌 Plugins (4)
AOS - Animations on scrollDialog - Template-free dialogsToast - NotificationsWait - Global loading states
Key Features ✅ Standalone Components - Import only what you need, zero bloat
✅ SSR/SSG Ready - Full Nuxt 3 support with auto-imports
✅ TypeScript-First - Complete type safety out of the box
✅ Dark Mode - Built-in dark/light theme switching
✅ Tree-Shakable - Optimized bundle sizes
✅ Responsive - Mobile-first design
✅ Accessible - ARIA-compliant components
✅ Themeable - 4 built-in presets + custom themes
✅ i18n - Multi-language support with @maz-ui/translations
✅ 840+ Icons - Optimized SVG icon library (@maz-ui/icons)
Template Structure Maz-UI provides two sets of production-ready templates organized by framework:
Vue 3 + Vite Templates (templates/vue/)
✅ Pure Vue 3 with Vite
✅ Uses standard fetch() API
✅ Explicit imports for all dependencies
✅ No framework-specific dependencies
✅ Optimized for SPA development
Use when : Building Vue 3 applications with Vite
setup/vite.config.ts - Vite configuration with auto-importscomponents/form-basic.vue - Basic form validationcomponents/form-multi-step.vue - Multi-step form with steppercomponents/dialog-confirm.vue - Dialog confirmation patternscomponents/data-table.vue - Data table with pagination, search, sort
Nuxt 3 Templates (templates/nuxt/)
✅ Nuxt 3 optimized
✅ Uses $fetch (Nuxt's ofetch wrapper)
✅ Leverages auto-imports for components and composables
✅ Showcases SSR patterns and server routes
✅ Optimized for full-stack Nuxt development
Use when : Building Nuxt 3 applications
setup/nuxt.config.ts - Nuxt configuration with Maz-UI modulecomponents/form-basic.vue - Basic form validation (auto-imports)components/form-multi-step.vue - Multi-step form (auto-imports)components/dialog-confirm.vue - Dialog patterns (auto-imports)components/data-table.vue - Data table with reactive data loading
✅ Fix all validation, type inference, and pagination issues
✅ Follow framework best practices
✅ Are production-ready and fully tested
✅ Include setup configs and component examples
When to Load References Load reference files based on what you're implementing. All 21 reference files are grouped by purpose for quick discovery:
Components (4 files)
components-forms.mdcomponents-feedback.mdcomponents-navigation.mdcomponents-layout.md
Setup & Configuration (2 files)
setup-vue.mdsetup-nuxt.md
Core Features (5 files)
composables.mddirectives.mdplugins.mdresolvers.mdCRITICAL : Auto-import configuration with MazComponentsResolver, MazDirectivesResolver, MazModulesResolver for optimal tree-shakingtranslations.md
Tools & Integrations (3 files)
icons.mdcli.mdmcp.md
Advanced Topics (5 files)
theming.mdperformance.mdssr-ssg.mdComprehensive SSR/SSG guide : theme strategies, critical CSS, hydration prevention, dark mode without flash, static site generationaccessibility.mdform-validation.md
Troubleshooting (2 files)
migration-v4.mdtroubleshooting.md
Top 6 Common Errors
1. Missing Theme Plugin Error Error : "useTheme must be used within MazUi plugin installation"
Cause : MazUi plugin not installed or theme composable disabled
Fix :
// Vue
app.use(MazUi, { theme: { preset: mazUi } })
// Nuxt
export default defineNuxtConfig({
mazUi: {
composables: { useTheme: true },
theme: { preset: 'maz-ui' }
}
})
2. Auto-Import Not Working (Nuxt) Error : Components/composables not found despite Nuxt module installed
Cause : Module not properly configured or cache issue
Fix :
# Clear Nuxt cache
rm -rf .nuxt node_modules/.cache
pnpm install
export default defineNuxtConfig({
modules: ['@maz-ui/nuxt']
})
3. Styles Not Applied Error : Components render but have no styling
Cause : CSS not imported
Fix Vue :
import 'maz-ui/styles' // Add this line
export default defineNuxtConfig({
mazUi: {
css: { injectMainCss: true } // Ensure this is true
}
})
4. TypeScript Errors with Components Error : Cannot find module 'maz-ui/components/MazBtn'
Cause : Missing type definitions or incorrect import path
Fix :
// Correct import
import MazBtn from 'maz-ui/components/MazBtn'
// Or with auto-import (Nuxt)
// No import needed, just use <MazBtn>
Ensure tsconfig.json includes:
{
"compilerOptions": {
"types": ["maz-ui/types"]
}
}
5. Phone Input Country Detection Fails Error : MazInputPhoneNumber doesn't detect country or shows wrong flag
Cause : Missing libphonenumber-js dependency or country data not loaded
Fix :
# Install peer dependency
pnpm add libphonenumber-js
<MazInputPhoneNumber
v-model="phone"
default-country-code="US"
preferred-countries="['US', 'CA', 'GB']"
/>
6. Translations Not Loading or Showing Raw Keys Error : Translation keys showing as raw strings like inputPhoneNumber.phoneInput.example instead of translated text
Causes :
Missing locale import
Lazy loading not awaited properly
Language file failed to load asynchronously
Missing preloadFallback configuration
SSR hydration mismatch (Nuxt)
Fix Vue (Immediate Loading):
import { fr } from '@maz-ui/translations'
app.use(MazUi, {
translations: {
locale: 'fr',
fallbackLocale: 'en',
preloadFallback: true,
messages: { fr } // Import immediately
}
})
app.use(MazUi, {
translations: {
locale: 'fr',
preloadFallback: true, // Ensure fallback is preloaded
messages: {
fr: () => import('@maz-ui/translations/locales/fr')
}
}
})
// In component: ALWAYS use await
const { setLocale } = useTranslations()
await setLocale('fr') // Don't forget await!
Fix Nuxt (Avoid Hydration):
import { fr } from '@maz-ui/translations'
export default defineNuxtConfig({
mazUi: {
translations: {
locale: 'fr',
preloadFallback: true,
messages: {
// CRITICAL: Provide initial locale immediately (not as function)
fr, // SSR requires immediate load
// Other languages can be lazy
es: () => import('@maz-ui/translations/locales/es')
}
}
}
})
<script setup>
const { setLocale } = useTranslations()
const toast = useToast()
async function switchLanguage(locale) {
try {
await setLocale(locale)
toast.success(`Language changed to ${locale}`)
} catch (error) {
console.error('Translation loading error:', error)
toast.error('Failed to load translations')
}
}
</script>
Learn More : Load references/translations.md for comprehensive i18n setup, lazy loading strategies, and production patterns.
Tree-Shaking Best Practices Direct Imports (Most Optimized):
// ✅✅✅ Best - smallest bundle
import MazBtn from 'maz-ui/components/MazBtn'
import { useToast } from 'maz-ui/composables/useToast'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'
// ✅ Good - tree-shakable
import { MazBtn, MazInput } from 'maz-ui/components'
import { useToast, useTheme } from 'maz-ui/composables'
Avoid (Not Tree-Shakable):
// ❌ Imports everything
import * as MazUI from 'maz-ui'
Advanced Topics
Performance Optimization Maz-UI can be optimized from ~300KB to ~15KB through strategic imports and tree-shaking. Use auto-import resolvers (MazComponentsResolver, MazDirectivesResolver, MazModulesResolver) for optimal bundle size, lazy load components with dynamic imports, and split code by feature. Load performance.md
SSR & SSG Full server-side rendering and static site generation support with three theme strategies: hybrid (critical CSS injection, no FOUC), buildtime (smallest bundle, static themes), and runtime (full theme switching, larger bundle). Prevent hydration mismatches by wrapping client-only components in <ClientOnly>. Load ssr-ssg.md
Accessibility All Maz-UI components are WCAG 2.1 AA compliant with proper ARIA attributes, keyboard navigation, focus management, and screen reader support. Components include semantic HTML, color contrast ratios >4.5:1, and accessible form validation. Load accessibility.md
Form Validation The useFormValidator() composable integrates with Valibot for type-safe schema validation with full TypeScript inference. Supports 5 validation modes (lazy, aggressive, eager, blur, progressive), async validation, custom validators, and real-time error messages. Load form-validation.md
Auto-Import Resolvers Critical for tree-shaking : Use unplugin-vue-components and unplugin-auto-import with Maz-UI resolvers to import only what you use. Reduces bundle size by 60-90% compared to global imports. Configure prefix handling to avoid naming conflicts with other libraries. Load resolvers.md
Progressive Disclosure Summary
Quick Start - Get running in <5 minutesCore Capabilities - Overview of all featuresError Prevention - Top 5 common issues solved For detailed implementation:
Load reference files based on your current task (see "When to Load References" above)
Each reference contains comprehensive guides, code examples, and advanced configurations
References are organized by domain (components, setup, theming, etc.) for easy navigation
Package Ecosystem
maz-ui - Core component library@maz-ui/nuxt - Nuxt 3 module with auto-imports@maz-ui/themes - Theming system and presets@maz-ui/translations - i18n support (8 built-in languages: en, fr, es, de, it, pt, ja, zh-CN)@maz-ui/icons - 840+ optimized SVG icons@maz-ui/mcp - AI agent documentation server
Official Resources 