MazPopover

MazPopover is a versatile Vue component for displaying content in overlays that bypass overflow constraints of parent elements

Basic usage

<template>
  <MazPopover>
    <template #trigger>
      <MazBtn>
        Click me
      </MazBtn>
    </template>
    <div class="p-4">
      <h3 class="mb-2 text-lg font-semibold">
        Popover Content
      </h3>
      <p class="text-sm">
        This is the content inside the popover.
      </p>
    </div>
  </MazPopover>

  <MazPopover trigger="hover">
    <template #trigger>
      <MazBtn color="secondary">
        Hover me
      </MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">
        This popover appears on hover!
      </p>
    </div>
  </MazPopover>
</template>

Adaptive trigger

The adaptive trigger mode automatically adapts to the user's device:

• Desktop: Uses hover behavior (mouseenter/mouseleave)
• Mobile/Touch devices: Uses click behavior

This provides the best user experience across all devices without requiring manual configuration.

<template>
  <!-- Basic adaptive trigger -->
  <MazPopover trigger="adaptive">
    <template #trigger>
      <MazBtn color="primary">
        Adaptive Trigger
      </MazBtn>
    </template>
    <div class="p-4">
      <h3 class="text-lg font-semibold mb-2">Smart Behavior</h3>
      <p class="text-sm mb-2">
        On desktop: Hover to open, move away to close
      </p>
      <p class="text-sm">
        On mobile: Tap to open, tap outside to close
      </p>
    </div>
  </MazPopover>

  <!-- Adaptive with keep-open-on-hover for menus -->
  <MazPopover trigger="adaptive" keep-open-on-hover>
    <template #trigger>
      <MazBtn color="secondary">
        Adaptive Menu
      </MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm mb-2">
        Perfect for dropdown menus that work on all devices
      </p>
      <button class="block w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 rounded-md">
        Menu Item 1
      </button>
      <button class="block w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 rounded-md">
        Menu Item 2
      </button>
    </div>
  </MazPopover>
</template>

Positions

TIP

The position prop is used to position the popover relative to the trigger. The chosen position will force the popover to be displayed in the chosen position.

<template>
  <MazPopover trigger="hover" position="top">
    <template #trigger>
      <MazBtn>Top</MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        Top positioned popover
      </p>
    </div>
  </MazPopover>

  <MazPopover trigger="hover" position="bottom">
    <template #trigger>
      <MazBtn>Bottom</MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        Bottom positioned popover
      </p>
    </div>
  </MazPopover>

  <MazPopover trigger="hover" position="left">
    <template #trigger>
      <MazBtn>Left</MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        Left positioned popover
      </p>
    </div>
  </MazPopover>

  <MazPopover trigger="hover" position="right">
    <template #trigger>
      <MazBtn>Right</MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        Right positioned popover
      </p>
    </div>
  </MazPopover>
</template>

Advanced positions

<template>
  <MazPopover position="top-start">
    <template #trigger>
      <MazBtn block size="sm">
        Top Start
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Top start aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="top-end">
    <template #trigger>
      <MazBtn block size="sm">
        Top End
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Top end aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="bottom-start">
    <template #trigger>
      <MazBtn block size="sm">
        Bottom Start
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Bottom start aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="bottom-end">
    <template #trigger>
      <MazBtn block size="sm">
        Bottom End
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Bottom end aligned</p>
    </div>
  </MazPopover>

  <MazPopover position="left-start">
    <template #trigger>
      <MazBtn block size="sm">
        Left Start
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Left start aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="left-end">
    <template #trigger>
      <MazBtn block size="sm">
        Left End
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Left end aligned</p>
    </div>
  </MazPopover>

  <MazPopover position="right-start">
    <template #trigger>
      <MazBtn block size="sm">
        Right Start
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Right start aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="right-end">
    <template #trigger>
      <MazBtn block size="sm">
        Right End
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">Right end aligned</p>
    </div>
  </MazPopover>

  <MazPopover position="auto">
    <template #trigger>
      <MazBtn color="accent">
        Auto Position
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        Automatically positioned based on available space
      </p>
    </div>
  </MazPopover>
</template>

Prefer position and fallback position

TIP

The prefer-position and fallback-position props are used to position the popover relative to the trigger. The prefer-position is the position that will be used if it's available, and the fallback-position is the position that will be used if the prefer-position is not available.

When you not specify a fallback position, the popover will fallback on the best position available.

<MazPopover prefer-position="top-start" fallback-position="bottom-start">
  <template #trigger>
    <MazBtn>
      Prefer position and fallback position
    </MazBtn>
  </template>
  <div class="p-4">
    <p class="text-sm">This popover will prefer the top position, but if it's not available, it will fallback to the bottom position.</p>
  </div>
</MazPopover>

Colors

<template>
  <MazPopover color="surface" trigger="hover">
    <template #trigger>
      <MazBtn color="contrast">Background</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a default color!</p>
    </div>
  </MazPopover>
  <MazPopover color="primary" trigger="hover">
    <template #trigger>
      <MazBtn color="primary">Primary</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a primary color!</p>
    </div>
  </MazPopover>
  <MazPopover color="secondary" trigger="hover">
    <template #trigger>
      <MazBtn color="secondary">Secondary</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a secondary color!</p>
    </div>
  </MazPopover>
  <MazPopover color="accent" trigger="hover">
    <template #trigger>
      <MazBtn color="accent">Accent</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a accent color!</p>
    </div>
  </MazPopover>
  <MazPopover color="contrast" trigger="hover">
    <template #trigger>
      <MazBtn color="contrast">Contrast</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a contrast color!</p>
    </div>
  </MazPopover>
  <MazPopover color="success" trigger="hover">
    <template #trigger>
      <MazBtn color="success">Success</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a success color!</p>
    </div>
  </MazPopover>
  <MazPopover color="info" trigger="hover">
    <template #trigger>
      <MazBtn color="info">Info</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a info color!</p>
    </div>
  </MazPopover>
  <MazPopover color="destructive" trigger="hover">
    <template #trigger>
      <MazBtn color="destructive">Destructive</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a destructive color!</p>
    </div>
  </MazPopover>
  <MazPopover color="warning" trigger="hover">
    <template #trigger>
      <MazBtn color="warning">Warning</MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">This popover has a warning color!</p>
    </div>
  </MazPopover>
</template>

Tooltip role

A directive is available to more easily add a tooltip to an element, see vTooltip for more information.

Hover this text

<template>
  <MazPopover role="tooltip" trigger="hover" position="top">
    <template #trigger>
      <MazBtn color="info">
        Hover for tooltip
      </MazBtn>
    </template>
    <div class="p-2">
      <p class="text-xs">This is a tooltip with proper ARIA attributes</p>
    </div>
  </MazPopover>
  <MazPopover
    role="tooltip"
    trigger="hover"
    position="bottom"
    panel-class="bg-gray-800! text-white! border-gray-700!"
  >
    <template #trigger>
      <span class="underline cursor-help">
        Hover this text
      </span>
    </template>
    <div class="p-2">
      <p class="text-xs">Custom styled tooltip</p>
    </div>
  </MazPopover>
  <MazPopover
    role="tooltip"
    trigger="hover"
    :delay="1000"
    position="right"
  >
    <template #trigger>
      <MazInformationCircle class="cursor-help text-info text-xl" />
    </template>
    <div class="p-2 max-w-48">
      <p class="text-xs">This tooltip has a 1000ms delay before showing</p>
    </div>
  </MazPopover>
</template>

Controlled popover

Popover is closed

<script setup>
import { ref } from 'vue'

const isOpen = ref(false)
</script>

<template>
  <MazPopover v-model="isOpen" trigger="manual">
    <template #trigger="{ toggle }">
      <MazBtn @click="toggle">
        Controlled Trigger
      </MazBtn>
    </template>
    <div class="p-4">
      <h4 class="font-semibold mb-2">Controlled Popover</h4>
      <p class="text-sm mb-3">This popover is controlled externally.</p>
      <MazBtn @click="isOpen = false" size="sm" color="destructive">
        Close
      </MazBtn>
    </div>
  </MazPopover>
  <MazBtn @click="isOpen = !isOpen" color="secondary">
    {{ isOpen ? 'Close' : 'Open' }} Popover
  </MazBtn>
  <span class="text-sm text-muted">
    Popover is {{ isOpen ? 'open' : 'closed' }}
  </span>

  <MazBtn color="secondary" @click="isOpen = !isOpen">
    {{ isOpen ? 'Close' : 'Open' }} Popover
  </MazBtn>
</template>

Menu example

<script setup>
const menuItems = [
  { label: 'Profile', icon: 'user', action: 'profile' },
  { label: 'Settings', icon: 'cog-6-tooth', action: 'settings' },
  { label: 'Sign out', icon: 'arrow-right-on-rectangle', action: 'signout' }
]

function handleMenuClick(action) {
  console.log('Menu action:', action)
}
</script>

<template>
  <MazPopover position="bottom-start">
    <template #trigger>
      <MazBtn>
        <MazIcon icon="/cog-6-tooth.svg" class="me-2" />
        Settings
        <MazIcon icon="/chevron-down.svg" class="ms-2" />
      </MazBtn>
    </template>
    <div class="py-1 min-w-48">
      <button
        v-for="item in menuItems"
        :key="item.label"
        class="w-full px-4 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 flex items-center gap-2"
        @click="handleMenuClick(item.action)"
      >
        <MazIcon :icon="item.icon" class="w-4 h-4" />
        {{ item.label }}
      </button>
    </div>
  </MazPopover>

  <MazPopover position="bottom-end">
    <template #trigger>
      <MazBtn color="transparent" size="sm">
        <MazIcon icon="/ellipsis-vertical.svg" />
      </MazBtn>
    </template>
    <div class="py-1 min-w-32">
      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
        Edit
      </button>
      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
        Share
      </button>
      <hr class="my-1 border-divider">
      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 text-destructive">
        Delete
      </button>
    </div>
  </MazPopover>
</template>

Keep open on hover

With this option, the popover will stay open when you hover over it (a timeout is used to close the popover after a certain time).

<template>
  <MazPopover position="bottom-end" keep-open-on-hover trigger="hover">
    <template #trigger>
      <MazBtn color="secondary">
        Keep open on hover
      </MazBtn>
    </template>
    <div class="py-1 min-w-32">
      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
        Edit
      </button>
      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
        Share
      </button>
      <hr class="my-1 border-divider">
      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 text-destructive">
        Delete
      </button>
    </div>
  </MazPopover>
</template>

Form example

<script setup>
import { reactive } from 'vue'

const formData = reactive({
  name: '',
  description: ''
})

function handleSubmit() {
  console.log('Form submitted:', formData)
  resetForm()
}

function resetForm() {
  formData.name = ''
  formData.description = ''
}
</script>

<template>
  <MazPopover position="bottom-start" :close-on-click-outside="false">
    <template #trigger>
      <MazBtn block>
        <MazIcon icon="/plus.svg" class="me-2" />
        Add Item
      </MazBtn>
    </template>
    <div class="w-80 p-4">
      <h3 class="mb-4 text-lg font-semibold">
        Add New Item
      </h3>
      <form class="space-y-4" @submit.prevent="handleSubmit">
        <MazInput
          v-model="formData.name"
          label="Name"
          placeholder="Enter item name"
          required
        />
        <MazTextarea
          v-model="formData.description"
          label="Description"
          placeholder="Enter description"
          rows="3"
        />
        <div class="flex gap-2">
          <MazBtn type="submit" color="success" size="sm">
            Save
          </MazBtn>
          <MazBtn type="button" color="transparent" size="sm" @click="resetForm">
            Reset
          </MazBtn>
        </div>
      </form>
    </div>
  </MazPopover>
</template>

Configuration options

Persistent (no auto-close)

Custom offset

Custom styling

Disabled state

<template>
  <!-- Persistent popover -->
  <MazPopover persistent>
    <template #trigger>
      <MazBtn color="warning">
        Persistent Popover
      </MazBtn>
    </template>
    <div class="p-4">
      <p class="mb-3 text-sm">
        This popover won't close on click outside or ESC.
      </p>
      <MazBtn size="sm" color="destructive" @click="close">
        Close manually
      </MazBtn>
    </div>
  </MazPopover>

  <!-- Custom offset -->
  <MazPopover :offset="20" position="top">
    <template #trigger>
      <MazBtn color="accent">
        Large Offset
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        20px offset from trigger
      </p>
    </div>
  </MazPopover>

  <!-- Custom styling -->
  <MazPopover
    panel-class="bg-linear-to-r from-purple-500 to-pink-500 text-white border-none"
    position="bottom"
  >
    <template #trigger>
      <MazBtn color="contrast">
        Styled Popover
      </MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm font-semibold">
        Beautiful gradient background!
      </p>
    </div>
  </MazPopover>

  <!-- Disabled -->
  <MazPopover disabled>
    <template #trigger>
      <MazBtn disabled>
        Disabled Popover
      </MazBtn>
    </template>
    <div class="p-3">
      <p class="text-sm">
        This won't show
      </p>
    </div>
  </MazPopover>
</template>

Events

Event Log:

No events yet. Try opening the popover above.

<script setup>
import { ref } from 'vue'

const events = ref([])

function onOpen() {
  console.log('Popover opened')
  events.value.push({
    type: 'open',
    time: new Date().toLocaleTimeString()
  })
}

function onClose() {
  console.log('Popover closed')
  events.value.push({
    type: 'close',
    time: new Date().toLocaleTimeString()
  })
}

function onToggle(isOpen) {
  console.log('Popover toggled:', isOpen)
  events.value.push({
    type: `toggle (${isOpen ? 'open' : 'close'})`,
    time: new Date().toLocaleTimeString()
  })
}
</script>

<template>
  <MazPopover
    @open="onOpen"
    @close="onClose"
    @toggle="onToggle"
  >
    <template #trigger>
      <MazBtn>
        Event Example
      </MazBtn>
    </template>
    <div class="p-4">
      <p class="text-sm">
        Check the console for events!
      </p>
    </div>
  </MazPopover>
</template>

Position values

• auto - Automatically choose best position
• top, bottom, left, right - Basic positions
• top-start, top-end - Top with start/end alignment
• bottom-start, bottom-end - Bottom with start/end alignment
• left-start, left-end - Left with start/end alignment
• right-start, right-end - Right with start/end alignment

Accessibility

MazPopover follows WAI-ARIA guidelines:

• Focus management: Automatically manages focus when opening/closing
• Keyboard navigation: Supports Escape key and Tab navigation
• ARIA attributes: Proper role, aria-modal, aria-labelledby, etc.
• Screen reader support: Appropriate roles for different use cases
• Trigger ARIA on the real control: aria-expanded, aria-haspopup and aria-controls are set on the interactive element of the trigger slot (your button, link...), never on a wrapper around it. ARIA attributes you set yourself on that element are kept, and a combobox keeps managing its own state. When the slot has no interactive element, the wrapper becomes a focusable button (Enter / Space toggle the popover).

Best practices

• Use role="tooltip" for simple informational overlays
• Use role="dialog" for interactive content
• Provide meaningful aria-labelledby or aria-describedby attributes
• Ensure trigger elements are focusable and have proper labels

Props

Name	Description	Type	Required	Default	Possible values
model-value	v-model Controls the popover open state	boolean	No	false	-
position	Position of the popover relative to trigger - Position of the popover relative to trigger	MazPopoverPosition	No	"auto"	'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'
prefer-position	Preferred position of the popover relative to trigger when auto position is used - Preferred position of the popover relative to trigger	MazPopoverPreferPosition	No	'bottom-start'	'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'
fallback-position	Fallback position of the popover relative to trigger when prefer position is not visible - Fallback position of the popover relative to trigger	MazPopoverFallbackPosition	No	auto	'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'
trigger	How the popover is triggered - How the popover is triggered. 'adaptive' uses hover on desktop and click on mobile	MazPopoverTrigger	No	"click"	'click' | 'hover' | 'manual' | 'adaptive'
role	ARIA role for accessibility - ARIA role for accessibility	MazPopoverRole	No	"dialog"	'dialog' | 'tooltip'
aria-label	ARIA label for the popover	string	No	-	-
announce-changes	Announce content changes to screen readers	boolean	No	false	-
disabled	Disables the popover - Disables the popover	boolean	No	false	-
offset	Distance between trigger and popover in pixels	number	No	8	-
delay	Delay before showing/hiding in milliseconds	number	No	0	-
hover-delay	Delay before closing on hover in milliseconds	number	No	150	-
transition	CSS transition name for animations - 'scale-pop' | 'scale-fade' for default transitions. 'scale-pop' is a pop effect, 'scale-fade' is a fade effect.	string	No	"scale-pop"	'scale-pop' | 'scale-fade' | 'string'
teleport-to	Teleport target selector	string	No	"body"	-
overlay-class	Additional CSS classes for the overlay wrapper	ClassValue	No	-	-
panel-class	Additional CSS classes for the popover panel	ClassValue	No	-	-
panel-style	Inline styles for the popover panel	StyleValue	No	-	-
close-on-click-outside	Close popover when clicking outside	boolean	No	true	-
close-on-escape	Close popover when pressing Escape key	boolean	No	true	-
persistent	Prevent auto-close (ignores click outside and escape key)	boolean	No	false	-
id	Custom ID for the popover element	string	No	-	-
aria-labelledby	ARIA labelledby attribute for accessibility	string	No	-	-
aria-describedby	ARIA describedby attribute for accessibility	string	No	-	-
color	Color variant of the popover	"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | "surface"	No	"surface"	'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent' | 'surface'
trap-focus	Trap focus inside the popover	boolean	No	true	-
keep-open-on-hover	Keep popover open when hovering over the panel	boolean	No	false	-
block	The popover will be full width of the trigger	boolean	No	false	-
position-reference	CSS selector or element reference to use for positioning calculations - When provided, the popover will position relative to this element instead of the trigger Useful for components with labels where you want to position relative to the actual input	string | HTMLElement	No	-	-

Events

Event name	Payload	Description
update:model-value	value: boolean	Emitted when popover state changes
open	-	Emitted when popover opens
close	-	Emitted when popover closes
toggle	value: boolean	Emitted when popover toggles
update:modelValue	value: boolean
after-close-animation	-	Emitted after the close animation

Slots

Name	Description	Bindings
trigger	Trigger element content	open () => void - Function to open the popover close () => void - Function to close the popover toggle () => void - Function to toggle the popover isOpen boolean - Current open state of the popover trigger "click" | "hover" | "manual" - The trigger type
default	Popover content	open () => void - Function to open the popover close () => void - Function to close the popover toggle () => void - Function to toggle the popover isOpen true - Current open state of the popover

Expose

open

Open the popover

close

Close the popover

toggle

Toggle the popover

isOpen

Check if the popover is open

updatePosition

Update the popover position

panelRef

Panel reference

onTransitionAfterLeave