---
title: "MazPopover"
description: "MazPopover is a versatile Vue component for displaying content in overlays that bypass overflow constraints of parent elements"
package: "maz-ui"
url: "https://maz-ui.com/components/maz-popover"
---

# MazPopover

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

- Package: `maz-ui`
- Import: `import MazPopover from 'maz-ui/components/MazPopover'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-popover

## Basic usage

```vue
<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.

```vue
<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.

```vue
<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

```vue
<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.

```html
<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

```vue
<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](../directives/tooltip.md) for more information.

```vue
<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

```vue
<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

```vue
<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).

```vue
<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

```vue
<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

```vue
<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

```vue
<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

## MazPopover API

`import MazPopover from 'maz-ui/components/MazPopover'`

### Props

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

### Events

- `@update:model-value` (payload: `value: boolean`): Emitted when popover state changes
- `@open`: Emitted when popover opens
- `@close`: Emitted when popover closes
- `@toggle` (payload: `value: boolean`): Emitted when popover toggles
- `@update:modelValue` (payload: `value: boolean`)
- `@after-close-animation`: Emitted after the close animation

### Slots

- `#trigger`: Trigger element content Bindings: `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 Bindings: `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).

### Exposed (template ref)

- `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`