secondsky/claude-skills / plugins/maz-ui/skills/maz-ui
maz-ui
VerifiedMaz-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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| references/accessibility.md | markdown | 16.2 KB |
| references/cli.md | markdown | 10.8 KB |
| references/components-feedback.md | markdown | 19.1 KB |
| references/components-forms.md | markdown | 8.4 KB |
| references/components-layout.md | markdown | 17.8 KB |
| references/components-navigation.md | markdown | 19.5 KB |
| references/composables.md | markdown | 28.3 KB |
| references/directives.md | markdown | 17.0 KB |
| references/form-validation.md | markdown | 22.7 KB |
| references/icons.md | markdown | 14.9 KB |
| references/mcp.md | markdown | 13.6 KB |
| references/migration-v4.md | markdown | 21.0 KB |
| references/performance.md | markdown | 17.0 KB |
| references/plugins.md | markdown | 25.1 KB |
| references/resolvers.md | markdown | 26.2 KB |
| references/setup-nuxt.md | markdown | 26.0 KB |
| references/setup-vue.md | markdown | 21.7 KB |
| references/ssr-ssg.md | markdown | 13.9 KB |
| references/theming.md | markdown | 7.2 KB |
| references/translations.md | markdown | 20.1 KB |
| references/troubleshooting.md | markdown | 9.0 KB |
references/directives.md
View on GitHub# Maz-UI Directives Guide
Maz-UI provides 5 Vue directives for common UI patterns like tooltips, click detection, and image handling. Directives are special attributes that apply reactive behavior to DOM elements.
**Last Verified**: 2026-08-03 | **Maz-UI Version**: 4.9.3
## Overview
Directives in Maz-UI:
- **v-tooltip** - Display tooltips on hover/focus
- **v-click-outside** - Detect clicks outside an element
- **v-lazy-img** - Lazy-load images with Intersection Observer
- **v-zoom-img** - Add zoom functionality to images
- **v-fullscreen-img** - Open images in fullscreen viewer
All directives are auto-imported in Nuxt 3 with `@maz-ui/nuxt` module. In Vue 3, directives must be registered globally or imported per component.
---
## Installation
### Vue 3
```typescript
// Import specific directive
import { vTooltip } from 'maz-ui/directives/vTooltip'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'
// Register globally
app.directive('tooltip', vTooltip)
app.directive('click-outside', vClickOutside)
```
### Nuxt 3
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@maz-ui/nuxt']
// All directives auto-imported!
})
```
**Usage in Components**:
```vue
<template>
<!-- No imports needed in Nuxt 3 -->
<div v-tooltip="'Hello World'">Hover me</div>
</template>
```
---
## v-tooltip
Display tooltips on hover or focus with customizable positioning and styling.
### Basic Usage
```vue
<template>
<!-- String value -->
<MazBtn v-tooltip="'Click to submit'">Submit</MazBtn>
<!-- Object with options -->
<MazBtn v-tooltip="{ text: 'Delete item', position: 'left' }">
Delete
</MazBtn>
</template>
```
### API
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `text` | `string` | - | Tooltip content (required) |
| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Tooltip position |
| `delay` | `number` | `0` | Show delay in milliseconds |
| `color` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info'` | `'primary'` | Tooltip color theme |
| `arrow` | `boolean` | `true` | Show arrow pointing to element |
### Syntax
**String (Simple)**:
```vue
<button v-tooltip="'Tooltip text'">Hover</button>
```
**Object (Advanced)**:
```vue
<button v-tooltip="{
text: 'Save changes',
position: 'bottom',
color: 'success',
delay: 300
}">
Save
</button>
```
**Reactive Value**:
```vue
<script setup lang="ts">
import { ref } from 'vue'
const tooltipText = ref('Initial tooltip')
function updateTooltip() {
tooltipText.value = 'Updated tooltip!'
}
</script>
<template>
<button v-tooltip="tooltipText" @click="updateTooltip">
Dynamic Tooltip
</button>
</template>
```
### Positioning
```vue
<template>
<div class="demo">
<button v-tooltip="{ text: 'Top tooltip', position: 'top' }">Top</button>
<button v-tooltip="{ text: 'Right tooltip', position: 'right' }">Right</button>
<button v-tooltip="{ text: 'Bottom tooltip', position: 'bottom' }">Bottom</button>
<button v-tooltip="{ text: 'Left tooltip', position: 'left' }">Left</button>
</div>
</template>
```
### Color Themes
```vue
<template>
<MazBtn v-tooltip="{ text: 'Primary action', color: 'primary' }">Primary</MazBtn>
<MazBtn v-tooltip="{ text: 'Danger zone!', color: 'danger' }">Delete</MazBtn>
<MazBtn v-tooltip="{ text: 'Success!', color: 'success' }">Save</MazBtn>
<MazBtn v-tooltip="{ text: 'Warning!', color: 'warning' }">Caution</MazBtn>
</template>
```
### Accessibility
- **ARIA**: Automatically adds `aria-label` attribute
- **Focus**: Tooltip shows on keyboard focus
- **Screen Readers**: Content announced to assistive technology
### Best Practices
1. **Keep text concise** - 1-2 sentences maximum
2. **Don't rely on tooltips alone** - Important info should be visible
3. **Use appropriate delays** - Immediate for icons, delayed for text buttons
4. **Avoid HTML content** - Use plain text for accessibility
5. **Position wisely** - Ensure tooltip doesn't overflow viewport
---
## v-click-outside
Detect clicks outside an element to close dropdowns, modals, or menus.
### Basic Usage
```vue
<script setup lang="ts">
import { ref } from 'vue'
const isOpen = ref(false)
function closeDropdown() {
isOpen.value = false
}
</script>
<template>
<div v-click-outside="closeDropdown" class="dropdown">
<button @click="isOpen = !isOpen">Toggle Menu</button>
<div v-if="isOpen" class="menu">
<a href="#">Option 1</a>
<a href="#">Option 2</a>
</div>
</div>
</template>
```
### API
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `handler` | `(event: Event) => void` | - | Function to call on outside click |
| `exclude` | `string[] \| HTMLElement[]` | `[]` | Elements to exclude from outside click detection |
| `events` | `string[]` | `['click']` | Events to listen for (e.g., `['click', 'touchstart']`) |
| `enabled` | `boolean` | `true` | Enable/disable directive |
### Syntax
**Function Handler (Simple)**:
```vue
<div v-click-outside="closeMenu">
<!-- Content -->
</div>
```
**Object with Options**:
```vue
<div v-click-outside="{
handler: closeMenu,
exclude: ['.modal-backdrop'],
events: ['click', 'touchstart']
}">
<!-- Content -->
</div>
```
### Excluding Elements
```vue
<script setup lang="ts">
import { ref } from 'vue'
const isOpen = ref(false)
const triggerRef = ref<HTMLElement>()
function close() {
isOpen.value = false
}
</script>
<template>
<button ref="triggerRef" @click="isOpen = !isOpen">
Open Menu
</button>
<div v-click-outside="{
handler: close,
exclude: [triggerRef]
}"
v-if="isOpen">
<!-- Clicking trigger button won't close menu -->
Menu content
</div>
</template>
```
### Conditional Activation
```vue
<script setup lang="ts">
const isEditing = ref(false)
function saveChanges() {
isEditing.value = false
// Save logic
}
</script>
<template>
<div v-click-outside="{
handler: saveChanges,
enabled: isEditing
}">
<!-- Only detect outside clicks when editing -->
</div>
</template>
```
### Common Use Cases
**Dropdown Menu**:
```vue
<script setup lang="ts">
const showDropdown = ref(false)
function closeDropdown() {
showDropdown.value = false
}
</script>
<template>
<div v-click-outside="closeDropdown" class="dropdown">
<MazBtn @click="showDropdown = !showDropdown">
Menu
</MazBtn>
<div v-if="showDropdown" class="dropdown-menu">
<a href="/profile">Profile</a>
<a href="/settings">Settings</a>
<a href="/logout">Logout</a>
</div>
</div>
</template>
```
**Modal Close**:
```vue
<script setup lang="ts">
const isModalOpen = ref(false)
function closeModal() {
isModalOpen.value = false
}
</script>
<template>
<div v-if="isModalOpen" class="modal-backdrop">
<div v-click-outside="closeModal" class="modal-content">
<!-- Modal content -->
<!-- Clicking backdrop closes modal -->
</div>
</div>
</template>
```
### Performance Considerations
- Event listeners are **added/removed automatically** with directive lifecycle
- Use `exclude` option to prevent unnecessary checks
- Consider disabling during animations for better performance
---
## v-lazy-img
Lazy-load images using Intersection Observer API for better performance.
### Basic Usage
```vue
<template>
<!-- Image loads when scrolled into view -->
<img v-lazy-img="'/images/photo.jpg'" alt="Photo" />
</template>
```
### API
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `src` | `string` | - | Image URL to lazy load |
| `placeholder` | `string` | - | Placeholder image URL while loading |
| `error` | `string` | - | Image to show if loading fails |
| `loading` | `string` | - | Loading spinner/image |
| `threshold` | `number` | `0.01` | Intersection Observer threshold (0-1) |
| `rootMargin` | `string` | `'0px'` | Margin around root (e.g., '50px' loads 50px before visible) |
### Syntax
**Simple (String)**:
```vue
<img v-lazy-img="imageUrl" alt="Description" />
```
**With Options (Object)**:
```vue
<img v-lazy-img="{
src: '/images/photo.jpg',
placeholder: '/images/placeholder.jpg',
error: '/images/error.jpg',
threshold: 0.5
}"
alt="Photo" />
```
### Placeholder & Error Handling
```vue
<script setup lang="ts">
const imageUrl = '/images/large-photo.jpg'
const placeholderUrl = '/images/blur-placeholder.jpg'
const errorUrl = '/images/image-not-found.jpg'
</script>
<template>
<img
v-lazy-img="{
src: imageUrl,
placeholder: placeholderUrl,
error: errorUrl
}"
alt="Product photo"
/>
</template>
```
### Preload Before Visible
```vue
<template>
<!-- Load images 100px before they enter viewport -->
<img
v-lazy-img="{
src: '/images/photo.jpg',
rootMargin: '100px'
}"
alt="Photo"
/>
</template>
```
### Loading State
```vue
<template>
<img
v-lazy-img="{
src: '/images/photo.jpg',
loading: '/images/spinner.gif'
}"
alt="Photo"
class="lazy-image"
/>
</template>
<style scoped>
.lazy-image {
min-height: 200px;
background: #f0f0f0;
}
</style>
```
### Intersection Observer Threshold
```vue
<template>
<!-- Load when 50% of image is visible -->
<img
v-lazy-img="{
src: '/images/photo.jpg',
threshold: 0.5
}"
alt="Photo"
/>
<!-- Load when fully visible -->
<img
v-lazy-img="{
src: '/images/photo.jpg',
threshold: 1.0
}"
alt="Photo"
/>
</template>
```
### Best Practices
1. **Always provide alt text** - Required for accessibility
2. **Use placeholders** - Improve perceived performance
3. **Set dimensions** - Prevent layout shift
4. **Optimize placeholder images** - Use small, blurred versions
5. **Use appropriate threshold** - Balance between early loading and performance
### SSR Compatibility
- ✅ Works in SSR (Nuxt)
- Placeholder shown on server, lazy loading on client
- No hydration mismatches
---
## v-zoom-img
Add zoom functionality to images on hover or click.
### Basic Usage
```vue
<template>
<!-- Hover to zoom -->
<img v-zoom-img="'/images/product.jpg'" alt="Product" />
</template>
```
### API
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `scale` | `number` | `2` | Zoom scale multiplier |
| `trigger` | `'hover' \| 'click'` | `'hover'` | Zoom trigger event |
| `duration` | `number` | `300` | Transition duration (ms) |
| `origin` | `'center' \| 'cursor'` | `'cursor'` | Zoom origin point |
### Syntax
**Simple**:
```vue
<img v-zoom-img="imageUrl" alt="Photo" />
```
**With Options**:
```vue
<img v-zoom-img="{
src: '/images/photo.jpg',
scale: 3,
trigger: 'click',
duration: 500
}"
alt="Photo" />
```
### Zoom on Hover
```vue
<template>
<img
v-zoom-img="{
src: '/images/product.jpg',
scale: 2,
trigger: 'hover'
}"
alt="Product"
class="product-image"
/>
</template>
<style scoped>
.product-image {
cursor: zoom-in;
transition: transform 0.3s ease;
}
</style>
```
### Zoom on Click
```vue
<template>
<img
v-zoom-img="{
src: '/images/artwork.jpg',
scale: 4,
trigger: 'click',
origin: 'center'
}"
alt="Artwork"
/>
</template>
```
### Use Cases
- **Product Images**: Allow customers to inspect details
- **Gallery**: Preview images before fullscreen
- **Documentation**: Zoom into diagrams or screenshots
- **Portfolio**: Showcase artwork details
---
## v-fullscreen-img
Open images in fullscreen viewer with zoom and navigation.
### Basic Usage
```vue
<template>
<!-- Click to open fullscreen -->
<img v-fullscreen-img="'/images/photo.jpg'" alt="Photo" />
</template>
```
### API
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `images` | `string[]` | - | Array of image URLs for gallery mode |
| `index` | `number` | `0` | Starting index in gallery |
| `closeOnBackdrop` | `boolean` | `true` | Close on backdrop click |
| `showNavigation` | `boolean` | `true` | Show prev/next buttons |
| `showZoom` | `boolean` | `true` | Show zoom controls |
### Syntax
**Single Image**:
```vue
<img v-fullscreen-img="'/images/photo.jpg'" alt="Photo" />
```
**Gallery Mode**:
```vue
<template>
<div class="gallery">
<img
v-for="(image, index) in images"
:key="image"
v-fullscreen-img="{
images: images,
index: index
}"
:src="image"
alt="Gallery photo"
/>
</div>
</template>
<script setup lang="ts">
const images = [
'/images/photo1.jpg',
'/images/photo2.jpg',
'/images/photo3.jpg'
]
</script>
```
### Fullscreen Options
```vue
<template>
<img
v-fullscreen-img="{
src: '/images/photo.jpg',
closeOnBackdrop: false,
showZoom: true,
showNavigation: false
}"
alt="Photo"
/>
</template>
```
### Gallery with Thumbnails
```vue
<script setup lang="ts">
const galleryImages = [
{ thumb: '/thumbs/1.jpg', full: '/full/1.jpg' },
{ thumb: '/thumbs/2.jpg', full: '/full/2.jpg' },
{ thumb: '/thumbs/3.jpg', full: '/full/3.jpg' }
]
const fullImages = galleryImages.map(img => img.full)
</script>
<template>
<div class="gallery-grid">
<img
v-for="(item, i) in galleryImages"
:key="i"
v-fullscreen-img="{
images: fullImages,
index: i
}"
:src="item.thumb"
alt="Gallery thumbnail"
class="thumbnail"
/>
</div>
</template>
```
### Keyboard Navigation
Fullscreen viewer supports:
- **Esc**: Close viewer
- **Arrow Left/Right**: Navigate gallery
- **+/-**: Zoom in/out
- **Space**: Toggle zoom
### Accessibility
- **Focus trap**: Keyboard navigation contained within viewer
- **ARIA labels**: Screen reader announcements
- **Keyboard support**: All functions accessible via keyboard
---
## Directive Registration (Vue 3)
### Global Registration
```typescript
// main.ts
import { createApp } from 'vue'
import {
vTooltip,
vClickOutside,
vLazyImg,
vZoomImg,
vFullscreenImg
} from 'maz-ui/directives'
const app = createApp(App)
app.directive('tooltip', vTooltip)
app.directive('click-outside', vClickOutside)
app.directive('lazy-img', vLazyImg)
app.directive('zoom-img', vZoomImg)
app.directive('fullscreen-img', vFullscreenImg)
app.mount('#app')
```
### Component-Level Registration
```vue
<script setup lang="ts">
import { vTooltip, vClickOutside } from 'maz-ui/directives'
// Directives available in this component only
</script>
<template>
<div v-tooltip="'Tooltip text'">
<button v-click-outside="closeMenu">Menu</button>
</div>
</template>
```
### Custom Directive Names
```typescript
// Use custom names to avoid conflicts
app.directive('maz-tooltip', vTooltip)
app.directive('maz-click-outside', vClickOutside)
```
---
## Best Practices
### Performance
1. **v-lazy-img**: Use for images below the fold
2. **v-tooltip**: Tooltips are lightweight, safe for many elements
3. **v-click-outside**: Automatically cleans up event listeners
4. **v-zoom-img**: Use `transform` for GPU acceleration
5. **v-fullscreen-img**: Only load fullscreen viewer when triggered
### Accessibility
1. **Tooltips**: Provide `aria-label` for screen readers
2. **Click-outside**: Ensure alternative close methods (Esc key, close button)
3. **Images**: Always include `alt` attributes
4. **Keyboard**: Test all directives with keyboard navigation
5. **Focus**: Ensure logical focus order
### SSR Considerations
| Directive | SSR Support | Notes |
|-----------|-------------|-------|
| `v-tooltip` | ✅ Full | Works in SSR |
| `v-click-outside` | ✅ Full | Event listeners added on client |
| `v-lazy-img` | ✅ Full | Shows placeholder on server |
| `v-zoom-img` | ⚠️ Partial | Initialize on client only |
| `v-fullscreen-img` | ⚠️ Partial | Viewer opens on client only |
---
## Troubleshooting
### Directive Not Working
**Problem**: Directive has no effect
```vue
<!-- ❌ Wrong: directive not registered -->
<div v-tooltip="'Text'">Hover</div>
<!-- ✅ Correct: register directive first -->
<script setup>
import { vTooltip } from 'maz-ui/directives'
</script>
<div v-tooltip="'Text'">Hover</div>
```
### Click-Outside Triggers Immediately
**Problem**: Click-outside fires on mount
**Solution**: Add small delay or exclude trigger element
```vue
<script setup>
const triggerRef = ref<HTMLElement>()
function close() {
// Handler
}
</script>
<template>
<button ref="triggerRef" @click="open">Open</button>
<div v-click-outside="{
handler: close,
exclude: [triggerRef]
}">
Content
</div>
</template>
```
### Lazy Images Not Loading
**Problem**: Images never load
**Causes**:
- Intersection Observer not supported (IE11)
- Image dimensions not set (0x0 size)
- Threshold too high
**Solution**:
```vue
<template>
<!-- Set explicit dimensions -->
<img
v-lazy-img="{
src: '/photo.jpg',
threshold: 0.01
}"
alt="Photo"
width="300"
height="200"
/>
</template>
```
---
## Related Documentation
- **Composables**: `references/composables.md`
- **Components**: `references/components-*.md`
- **Accessibility**: `references/accessibility.md`
- **Performance**: `references/performance.md`
---
**Last Updated**: 2026-08-03 | **Maz-UI Version**: 4.9.3
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |