Maz UI Documentation

Maz UI is a lightweight, tree-shakeable library for Vue and Nuxt designed with a mobile-first, responsive approach. It includes full TypeScript support and is SSR-ready.

Core Modules

• Components: Accessible UI components.
• Plugins: Logic for common use cases (e.g., dialogs).
• Composables: Reusable logic (e.g., form validation).
• Directives: Vue directives (e.g., fullscreen image).
• Helpers: Utility functions (e.g., currency formatting).

Available Packages

• @maz-ui/themes: CSS variable-based theming.
• @maz-ui/translations: Internationalization support.
• @maz-ui/icons: Vue-ready icon set.
• @maz-ui/nuxt: Nuxt integration module.
• @maz-ui/node: Node.js utilities.
• @maz-ui/mcp: MCP Server for AI documentation assistance.

The maz-ui ecosystem consists of several specialized packages:

• maz-ui: The core library containing 62 components, 22 composables, 6 directives, and 6 plugins.
• @maz-ui/nuxt: Nuxt 3 module for auto-imports and SSR support.
• @maz-ui/themes: The theming engine with presets and design tokens.
• @maz-ui/icons: A collection of 860+ SVG icons.
• @maz-ui/translations: i18n support for 9 locales.
• @maz-ui/mcp: A Model Context Protocol server that allows AI agents to access maz-ui documentation natively.

Maz-UI is a lightweight and efficient library of standalone components, plugins, directives, and composables designed for Vue and Nuxt.

Key Features:

• Standalone: All components and tools are modular. You can install and use only the specific modules you need without the entire library.
• SSR Friendly: Fully compatible with Nuxt, ensuring components work seamlessly with Server-Side Rendering without requiring client-side-only installation.
• TypeScript Support: Written in TypeScript, providing full type safety and declarations out of the box.
• Theming: Built with TailwindCSS, optimized for CSS file size, and supports easy theme customization.
• Dark and Light Modes: All components natively support both light and dark themes.

Maz-UI v4 is composed of several specialized packages to extend functionality:

• @maz-ui/icons: An SVG icon library with 860+ icons, provided as Vue components, direct SVG files, and supporting auto-import.
• @maz-ui/nuxt: A Nuxt module providing auto-imports and SSR support.
• @maz-ui/themes: Contains pre-built theme collections and design tokens.
• @maz-ui/translations: A lightweight i18n system for components.
• @maz-ui/mcp: A Model Context Protocol server that connects AI agents to Maz-UI documentation.

MazChart is a standalone Vue component that wraps chart.js to generate various types of graphics and charts. It is highly compatible with the Chart.JS ecosystem, allowing you to use all Chart.JS plugins and configurations. You can pass chart configurations directly via props or use v-bind to pass a complete configuration object.

<template>
  <MazChart
    :type="chartConfig.type"
    :data="chartConfig.data"
    :options="chartConfig.options"
  />
</template>

The Maz-UI MCP server (@maz-ui/mcp) acts as a bridge between your AI assistant and Maz-UI's documentation. It allows AI assistants to search, read, and suggest implementations based on the official Maz-UI technical content.

By connecting this server, your AI assistant gains access to:

• 50+ Vue components (including props, events, and examples)
• 14+ composables and utilities
• 11 comprehensive guides (installation, theming, migration, etc.)
• 5 directives and 4 plugins (Toast, dialog, AOS, and wait overlay)
• 20+ helper functions

Security Note: The server provides read-only access to documentation. No sensitive data is transmitted or stored.

The MazDatePicker component can be configured for different selection behaviors:

• Standard Date Picker: Default selection mode.
• Inline Date Picker: Renders the calendar directly in the UI without a dropdown.
• Double Calendar: Displays two calendars side-by-side, useful for range selection.
• Time Selection: Supports 12-hour or 24-hour formats. You can select time only or date and time combined.
• Range Selection: Allows selecting a start and end date.

Time Formats

• 24-hour: Use 24h format (e.g., 14:30).
• 12-hour: Use 12h format with AM/PM (e.g., 02:30 pm).

Maz-UI supports three rendering strategies for CSS injection:

1. Hybrid (Recommended): Combines critical CSS injection (to prevent FOUC) with asynchronous loading of full CSS via requestIdleCallback. This balances speed and performance.
2. Runtime: Generates and injects both critical and full CSS immediately. Warning: This can block the main thread and impact performance.
3. Buildtime: CSS is generated at build-time and included in the bundle. Requires building CSS files before running the app.

// Example: Hybrid strategy
import { mazUi } from '@maz-ui/themes/presets'

app.use(MazUi, {
  theme: {
    preset: mazUi,
    strategy: 'hybrid'
  }
})

MazBottomSheet is a standalone component designed to act like a simple dialog positioned at the bottom of the screen. It is particularly useful for improving mobile user experiences.

Implementation Note: The component uses <Teleport to="body"> along with MazBackdrop. This means you can place the <MazBottomSheet> component anywhere in your component tree, and it will be rendered at the body level, inheriting all its props correctly.

Maz-UI supports dynamic variables within translation strings using curly brace syntax. These variables are automatically replaced with the provided values at runtime.

Common patterns:

• {example}: e.g., Example: {example} becomes Example: +33 6 12 34 56 78.
• {page}: e.g., Page {page} becomes Page 3.
• {count}, {size}, {types}: Used in components like dropzone for dynamic metadata.

// Example translation object structure
export default {
  dropzone: {
    fileMaxCount: 'Maximum {count} fichiers',
    fileMaxSize: 'Maximum {size} MB',
    fileTypes: 'Types de fichiers autorisés: {types}'
  }
}