Getting Started

Build Vue and Nuxt applications faster with Maz-UI v4 - The modern, modular component library

Why Maz-UI?

• 🌱 Tree-shaking - Import only what you need
• 🛠️ TypeScript-first - Full type safety out of the box
• 🚀 Performance - Tree-shaking benefits and maximum optimization
• 🎨 Theming system - Customizable themes and dark mode support (4 presets available) - @maz-ui/themes
• 🌐 Internationalization - Locale management and tree-shakable imports - @maz-ui/translations
• 🎨 Icon library - Comprehensive collection of SVG icons designed for performance and flexibility (400+ icons) - @maz-ui/icons
• 🧰 Nuxt module - Effortless Maz-UI integration with auto-imports - @maz-ui/nuxt
• 🤖 MCP - Connect your IA agents to the documentation - @maz-ui/mcp

Guides

Start by choosing your framework:

Vue Users Guide

Vue guide

Nuxt Users Guide

Nuxt guide

Ecosystem Packages

Extend Maz-UI with our specialized companion packages:

@maz-ui/themes

Advanced Theming System

Modern theme system with HSL variables, dark mode support, and flexible strategies.

npm install @maz-ui/themes

Features:

• 🎨 HSL CSS custom properties
• 🌓 Smart dark mode detection
• ⚡ Multiple rendering strategies
• 🛡️ Full TypeScript support

→ View Theme Documentation

---

@maz-ui/translations

Internationalization (i18n)

Internationalization library for Maz-UI.

npm install @maz-ui/translations

Features:

• 🌐 Internationalization of Maz-UI components
• 🔄 Locale management
• 📦 Tree-shakable imports
• 🛠️ TypeScript support

→ View Translations Documentation

---

@maz-ui/icons

Optimized Icon Library

Comprehensive collection of SVG icons designed for performance and flexibility.

npm install @maz-ui/icons

Features:

• 860+ icons
• Usable as Vue components (e.g. <MazStar />)
• Tree-shakable imports
• Multiple sizes and variants
• Full TypeScript definitions

→ Browse Icon Library

---

@maz-ui/mcp

Maz-UI MCP server to connect your IA agents to the documentation

Features:

• Connect your IA agents to the documentation

→ View MCP Documentation

Performance Optimizations

Tree-Shaking Benefits

Maz-UI v4 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:

/**
 * Utilities
 */

// ❌ Avoid importing everything
import { formatCurrency, debounce } from 'maz-ui'
// ✅ Import from @maz-ui/utils
import { formatCurrency, debounce } from '@maz-ui/utils'

/**
 * Components
 */

// ✅ Import specific components (good)
import { MazBtn, MazCard, MazInput } from 'maz-ui/components'
// ✅✅ Direct component import (most optimized)
import MazBtn from 'maz-ui/components/MazBtn'
import MazCard from 'maz-ui/components/MazCard'
import MazInput from 'maz-ui/components/MazInput'

/**
 * Composables
 */

// ✅ Import composable from index file
import { useBreakpoints, useToast } from 'maz-ui/composables'

// ✅✅ Direct composable import (most optimized)
import { useToast } from 'maz-ui/composables/useToast'
import { useBreakpoints } from 'maz-ui/composables/useBreakpoints'

/**
 * Directives
 */

// ✅ Import directive from index file
import { vClickOutside } from 'maz-ui/directives'

// ✅✅ Direct directive import (most optimized)
import { vClickOutside } from 'maz-ui/directives/vClickOutside'

// ✅✅✅ Even better: auto-import does this automatically
// Components, composables, and utilities are imported only when used

/**
 * Plugins
 */

// ✅ Import plugin from index file
import { MazUi } from 'maz-ui/plugins'
// ✅✅ Direct plugin import (most optimized)
import { MazUi } from 'maz-ui/plugins/maz-ui'

Maximum Optimization

Direct imports (e.g., import MazBtn from 'maz-ui/components/MazBtn') are the most optimized approach as they bypass index files completely. This ensures the smallest possible bundle size and fastest build times.

Next Steps

Explore Components

Browse the component library with live examples and API documentation.

Customize Themes

Learn about theming and customization to match your brand.

Internationalization

Learn about internationalization to support multiple languages.

Lazy Loading with MazUiProvider

Use MazUiProvider to defer Maz-UI initialization to lazy-loaded pages for zero entry-bundle overhead.

Get Help

Browse GitHub discussions or open an issue on GitHub.