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="maz-p-4">
      <h3 class="maz-mb-2 maz-text-lg maz-font-semibold">
        Popover Content
      </h3>
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <h3 class="maz-text-lg maz-font-semibold maz-mb-2">Smart Behavior</h3>
      <p class="maz-text-sm maz-mb-2">
        On desktop: Hover to open, move away to close
      </p>
      <p class="maz-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="maz-p-4">
      <p class="maz-text-sm maz-mb-2">
        Perfect for dropdown menus that work on all devices
      </p>
      <button class="maz-block maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400 maz-rounded">
        Menu Item 1
      </button>
      <button class="maz-block maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400 maz-rounded">
        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="maz-p-3">
      <p class="maz-text-sm">
        Top positioned popover
      </p>
    </div>
  </MazPopover>

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

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

  <MazPopover trigger="hover" position="right">
    <template #trigger>
      <MazBtn>Right</MazBtn>
    </template>
    <div class="maz-p-3">
      <p class="maz-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="maz-p-3">
      <p class="maz-text-sm">Top start aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="top-end">
    <template #trigger>
      <MazBtn block size="sm">
        Top End
      </MazBtn>
    </template>
    <div class="maz-p-3">
      <p class="maz-text-sm">Top end aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="bottom-start">
    <template #trigger>
      <MazBtn block size="sm">
        Bottom Start
      </MazBtn>
    </template>
    <div class="maz-p-3">
      <p class="maz-text-sm">Bottom start aligned</p>
    </div>
  </MazPopover>
  <MazPopover position="bottom-end">
    <template #trigger>
      <MazBtn block size="sm">
        Bottom End
      </MazBtn>
    </template>
    <div class="maz-p-3">
      <p class="maz-text-sm">Bottom end aligned</p>
    </div>
  </MazPopover>

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

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

  <MazPopover position="auto">
    <template #trigger>
      <MazBtn color="accent">
        Auto Position
      </MazBtn>
    </template>
    <div class="maz-p-3">
      <p class="maz-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="maz-p-4">
    <p class="maz-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="background" trigger="hover">
    <template #trigger>
      <MazBtn color="contrast">Background</MazBtn>
    </template>
    <div class="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-4">
      <p class="maz-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="maz-p-2">
      <p class="maz-text-xs">This is a tooltip with proper ARIA attributes</p>
    </div>
  </MazPopover>
  <MazPopover
    role="tooltip"
    trigger="hover"
    position="bottom"
    panel-class="!maz-bg-gray-800 !maz-text-white !maz-border-gray-700"
  >
    <template #trigger>
      <span class="maz-underline maz-cursor-help">
        Hover this text
      </span>
    </template>
    <div class="maz-p-2">
      <p class="maz-text-xs">Custom styled tooltip</p>
    </div>
  </MazPopover>
  <MazPopover
    role="tooltip"
    trigger="hover"
    :delay="1000"
    position="right"
  >
    <template #trigger>
      <MazInformationCircle class="maz-cursor-help maz-text-info maz-text-xl" />
    </template>
    <div class="maz-p-2 maz-max-w-48">
      <p class="maz-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="maz-p-4">
      <h4 class="maz-font-semibold maz-mb-2">Controlled Popover</h4>
      <p class="maz-text-sm maz-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="maz-text-sm maz-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 name="cog-6-tooth" class="maz-mr-2" />
        Settings
        <MazIcon name="chevron-down" class="maz-ml-2" />
      </MazBtn>
    </template>
    <div class="maz-py-1 maz-min-w-48">
      <button
        v-for="item in menuItems"
        :key="item.label"
        class="maz-w-full maz-px-4 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400 maz-flex maz-items-center maz-gap-2"
        @click="handleMenuClick(item.action)"
      >
        <MazIcon :name="item.icon" class="maz-w-4 maz-h-4" />
        {{ item.label }}
      </button>
    </div>
  </MazPopover>

  <MazPopover position="bottom-end">
    <template #trigger>
      <MazBtn color="transparent" size="sm">
        <MazIcon name="ellipsis-vertical" />
      </MazBtn>
    </template>
    <div class="maz-py-1 maz-min-w-32">
      <button class="maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400">
        Edit
      </button>
      <button class="maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400">
        Share
      </button>
      <hr class="maz-my-1 maz-border-divider">
      <button class="maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400 maz-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="maz-py-1 maz-min-w-32">
      <button class="maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400">
        Edit
      </button>
      <button class="maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400">
        Share
      </button>
      <hr class="maz-my-1 maz-border-divider">
      <button class="maz-w-full maz-px-3 maz-py-2 maz-text-left maz-text-sm hover:maz-bg-surface-600 dark:hover:maz-bg-surface-400 maz-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 name="plus" class="maz-mr-2" />
        Add Item
      </MazBtn>
    </template>
    <div class="maz-w-80 maz-p-4">
      <h3 class="maz-mb-4 maz-text-lg maz-font-semibold">
        Add New Item
      </h3>
      <form class="maz-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="maz-flex maz-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="maz-p-4">
      <p class="maz-mb-3 maz-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="maz-p-3">
      <p class="maz-text-sm">
        20px offset from trigger
      </p>
    </div>
  </MazPopover>

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

  <!-- Disabled -->
  <MazPopover disabled>
    <template #trigger>
      <MazBtn disabled>
        Disabled Popover
      </MazBtn>
    </template>
    <div class="maz-p-3">
      <p class="maz-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="maz-p-4">
      <p class="maz-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

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	undefined	-
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" | string	No	popover	-
teleport-to	Teleport target selector	string	No	body	-
overlay-class	Additional CSS classes for the overlay wrapper	Native type	No	undefined	-
panel-class	Additional CSS classes for the popover panel	Native type	No	undefined	-
panel-style	Inline styles for the popover panel	Native type	No	undefined	-
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	undefined	-
aria-labelledby	ARIA labelledby attribute for accessibility	string	No	undefined	-
aria-describedby	ARIA describedby attribute for accessibility	string	No	undefined	-
color	Color variant of the popover	MazColor | "background"	No	background	primary, secondary, accent, info, success, warning, destructive, contrast, background
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 Example: "input" or "#my-input" or HTMLElement	string | HTMLElement	No	undefined	-

Events

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

Slots

Name	Description	Bindings
trigger	Trigger element content	open function - Function to open the popover close function - Function to close the popover toggle function - Function to toggle the popover is-open boolean - Current open state of the popover trigger 'click' | 'hover' | 'manual' - The trigger type
default	Popover content	open function - Function to open the popover close function - Function to close the popover toggle function - Function to toggle the popover is-open boolean - Current open state of the popover

Expose

open

Open the popover
@description Programmatically open the popover
@usage mazPopoverInstance.value?.open()

close

Close the popover
@description Programmatically close the popover
@usage mazPopoverInstance.value?.close()

toggle

Toggle the popover
@description Programmatically toggle the popover open/close state
@usage mazPopoverInstance.value?.toggle()

isOpen

Check if the popover is open
@description Reactive reference to the popover open state
@usage const isPopoverOpen = mazPopoverInstance.value?.isOpen

updatePosition

Update the popover position
@description Manually recalculate and update the popover position
@usage mazPopoverInstance.value?.updatePosition()