---
title: "MazDropdown"
description: "MazDropdown is a standalone dropdown menu component and versatile designed for various use cases."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-dropdown"
---

# MazDropdown

> MazDropdown is a standalone dropdown menu component and versatile designed for various use cases.

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

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

**Tip:**

This component can be translated globally using the [MazUi](https://maz-ui.com/ecosystem/translations.md) plugin.

## Basic usage

```vue
<template>
  <MazDropdown
    :items="[
      { label: 'Action', onClick: () => toast.success('CLICKED') },
      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank', color: 'secondary' },
      { label: 'Router Link', to: { name: 'index' }, color: 'destructive' },
    ]"
  >
    Dropdown Menu
  </MazDropdown>
</template>

<script lang="ts" setup>
  import MazDropdown from 'maz-ui/components/MazDropdown'
</script>
```

## Open dropdown with 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.

```html{7}
<MazDropdown
  :items="[
    { label: 'Action', onClick: () => toast.success('CLICKED') },
    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
    { label: 'Router Link', to: { name: 'index' } },
  ]"
  trigger="adaptive"
>
  Adaptive trigger
</MazDropdown>
```

## Open dropdown only on click

```html{7}
<MazDropdown
  :items="[
    { label: 'Action', onClick: () => toast.success('CLICKED') },
    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
    { label: 'Router Link', to: { name: 'index' } },
  ]"
  trigger="click"
>
  Click me
</MazDropdown>
```

## Open dropdown only on hover

```html{7}
<MazDropdown
  :items="[
    { label: 'Action', onClick: () => toast.success('CLICKED') },
    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
    { label: 'Router Link', to: { name: 'index' } },
  ]"
  trigger="hover"
>
  Hover me
</MazDropdown>
```

## Custom dropdown icon

You can provide an icon to replace the default chevron icon and disable the animation

```vue{7}
<script lang="ts" setup>
  // Use vite-svg-loader to import SVG as Vue component
  import MazChevronUpDown from '@maz-ui/icons/chevron-up-down.svg?component'
</script>

<template>
  <MazDropdown
    :items="[
      { label: 'Action', onClick: () => toast.success('CLICKED') },
      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
      { label: 'Router Link', to: { name: 'index' } },
    ]"
    trigger="hover"
    :dropdown-icon="MazChevronUpDown"
  >
    Hover me
  </MazDropdown>

  <MazDropdown
    :items="[
      { label: 'Action', onClick: () => toast.success('CLICKED') },
      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
      { label: 'Router Link', to: { name: 'index' } },
    ]"
    trigger="hover"
    :dropdown-icon="MazChevronUpDown"
    :dropdown-icon-animation="false"
  >
    No icon animation
  </MazDropdown>
</template>
```

`dropdownIcon` also accepts a full `MazIconProps` object - pass the same shape `<MazIcon>` accepts when you need to set a `<title>` for screen readers, override the size, or attach `svgAttributes`.

```vue
<MazDropdown
  :items="items"
  :dropdown-icon="{
    icon: MazChevronUpDown,
    size: 'lg',
    title: 'Open menu',
  }"
>
  Custom icon
</MazDropdown>
```

## Custom dropdown main button without chevron icon

**Tip:**

  This component uses [MazBtn](./maz-btn.md) has a menu button, so it inherits all its props

**Details: View code**

```vue{7-13}
<script lang="ts" setup>
  import { MazBars3 } from '@maz-ui/icons/raw/MazBars3'
</script>

<template>
  <MazDropdown
    color="primary"
    fab
    pastel
    :chevron="false"
    :icon="MazBars3"
    items-size="sm"
    size="xl"
    :items="[
      { label: 'Action', onClick: () => toast.success('CLICKED') },
      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
      { label: 'Router Link', to: { name: 'index' } },
    ]"
    :close-on-click="false"
  />
</template>
```

## Custom slots

### Custom dropdown panel

You can provide a template to replace the default dropdown panel

**Details: View code**

```html
<MazDropdown>
  Customized dropdown panel

  <template #dropdown>
    <div class="grid grid-cols-3 gap-2">
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
      <MazBtn color="transparent"> Item </MazBtn>
    </div>
  </template>
</MazDropdown>
```

### Custom menuitem labels

You can provide a template to replace menuitem labels to add more elements in each menuitem

**Details: View code**

```html
<MazDropdown
  :items="[
    { label: 'Action', onClick: () => toast.success('CLICKED'), additionnalData: 'https://placedog.net/240/200' },
    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank', additionnalData: 'https://placedog.net/340/300' },
    { label: 'Router Link', to: { name: 'index' }, additionnalData: 'https://placedog.net/440/400' },
  ]"
>
  <template #default>
    Customized labels
  </template>

  <template #menuitem-label="{ item }">
    <div class="flex items-center gap-2">
      <MazAvatar :src="item.additionnalData" />
      <span>
        {{ item.label }}
      </span>
    </div>
  </template>
</MazDropdown>
```

### Custom control triggered element

You can provide an HTML element or a component to replace the default button

**Warning:**

Add `tabindex="-1"` attribute to your element to avoid a double focus with Tab key

**Details: View code**

```html
<MazDropdown
  :items="[
    {
      label: 'Action',
      onClick: () => toast.success('CLICKED'),
      additionnalData: 'https://placedog.net/240/200',
    },
    {
      label: 'Link (href)',
      href: 'https://www.google.com',
      target: '_blank',
      additionnalData: 'https://placedog.net/340/300',
    },
    {
      label: 'Router Link',
      to: { name: 'index' },
      additionnalData: 'https://placedog.net/440/400',
    },
  ]"
>
  <template #element>
    <MazAvatar
      clickable
      hide-clickable-icon
      src="https://cdn.artphotolimited.com/images/5ff5a529bd40b83c5a537440/1000x1000/gerard-depardieu-1983.jpg"
      tabindex="-1"
    />
  </template>
</MazDropdown>

<MazDropdown
  position="top"
  :items="[
    {
      label: 'Action',
      onClick: () => toast.success('CLICKED'),
      additionnalData: 'https://placedog.net/240/200',
    },
    {
      label: 'Link (href)',
      href: 'https://www.google.com',
      target: '_blank',
      additionnalData: 'https://placedog.net/340/300',
    },
    {
      label: 'Router Link',
      to: { name: 'index' },
      additionnalData: 'https://placedog.net/440/400',
    },
  ]"
>
  <template #element="{ isOpen }">
    <button class="border border-solid border-divider-400 p-2 hover:bg-surface-400" tabindex="-1">
      HTMLButtonElement: isOpen {{ isOpen }}
    </button>
  </template>
</MazDropdown>
```

## Open programmatically

isOpen:

```vue
<template>
  <MazDropdown
    v-model="isOpen"
    :items="[
      { label: 'Action', onClick: () => toast.success('CLICKED') },
      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
      { label: 'Router Link', to: { name: 'index' } },
    ]"
  >
    Open
  </MazDropdown>

  <MazBtn @click="isOpen = !isOpen">
    Open Dropdown
  </MazBtn>
</template>

<script lang="ts" setup>
  import { ref } from 'vue'

  const isOpen = ref(false)
</script>
```

## Position

## Types

### MazDropdownMenuItem

```ts
type MazDropdownMenuItem = {
  label: string
  onClick?: () => unknown
  target?: string
  href?: string
  to?: RouteLocationRaw
  class?: string
} & Record<string, unknown>
```

## Accessibility

The trigger button exposes the menu state (`aria-haspopup="menu"`, `aria-expanded`, `aria-controls`), the panel is a `menu` and each item a `menuitem`. ↓ / ↑ move between the items, Enter runs the focused item and Esc closes the menu.

## MazDropdown API

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

### Props

- `model-value` (`boolean`, default: `false`, `v-model`): Controls whether the dropdown menu is open.
- `items` (`MazDropdownMenuItem[]`, default: `[]`): Menu items to display in the dropdown Each item can be either a link (with href/to properties) or an action (with onClick function).
- `items-size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Size of the dropdown menu items.
- `id` (`string`): Unique identifier for the dropdown component.
- `trigger` (`MazPopoverTrigger`, default: `"adaptive"`): Determines how the dropdown should be triggered. Values: `'click'`, `'hover'`, `'manual'`, `'adaptive'` (non exhaustive).
- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"transparent"`): Color theme for the dropdown button.
- `position` (`MazPopoverPosition`, default: `"auto"`): Position of the menu 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).
- `close-on-click` (`boolean`, default: `false`): Controls whether the dropdown menu closes when a menu item is clicked.
- `disabled` (`boolean`, default: `false`): Disables the dropdown functionality.
- `chevron` (`boolean`, default: `true`): Controls whether to show the chevron icon in the trigger button.
- `screen-reader-description` (`string`, default: `MazUiTranslationsSchema['dropdown']['screenReaderDescription']`): Accessible description for screen readers describing the dropdown functionality If not provided, the default translation of MazUiTranslations plugin will be used.
- `menu-panel-class` (`ClassValue`): Additional CSS classes to apply to the dropdown menu panel Useful for customizing the dropdown appearance (background, border, etc.).
- `menu-panel-style` (`StyleValue`): Inline styles to apply to the dropdown menu panel Useful for custom styling. You may use `!important` to override default styles.
- `block` (`boolean`, default: `false`): Makes the dropdown button expand to full width of its container.
- `dropdown-icon` (`MazIconLike`): Icon to use instead of the default chevron for the dropdown indicator Custom icon to display in place of the default chevron. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
- `dropdown-icon-animation` (`boolean`, default: `true`): Controls whether the dropdown icon rotates when the dropdown is opened.
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the dropdown button.
- `transition` (`string`, default: `"scale-pop"`): Transition to use when the dropdown is opened or closed. Values: `'scale-pop'`, `'scale-fade'`, `'string'` (non exhaustive).
- `delay` (`number`, default: `0`): Delay before showing/hiding in milliseconds.
- `persistent` (`boolean`, default: `false`): Prevent auto-close (ignores click outside and escape key).
- `close-on-escape` (`boolean`, default: `true`): Close popover when pressing Escape key.
- `aria-labelledby` (`string`): ARIA labelledby attribute for accessibility.
- `aria-describedby` (`string`): ARIA describedby attribute for accessibility.
- `aria-label` (`string`): ARIA label for the popover.
- `offset` (`number`, default: `8`): Distance between trigger and popover in pixels.
- `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).
- `announce-changes` (`boolean`, default: `false`): Announce content changes to screen readers.
- `hover-delay` (`number`, default: `150`): Delay before closing on hover in milliseconds.
- `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.
- `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.
- `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 the dropdown open state changes
- `@update:modelValue` (payload: `value: boolean`)
- `@menuitem-clicked` (payload: `event: Event`): Emitted when a menu item is clicked

### Slots

- `#screen-reader-description`: description for screen readers (hidden from visual display)
- `#trigger`: trigger element for the dropdown Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown), `close: () => void` (Function to close the dropdown), `open: () => void` (Function to open the dropdown).
- `#default`: Text content of the trigger element
- `#dropdown-icon`: Dropdown indicator icon Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void`, `close: () => void`, `open: () => void`.
- `#dropdown`: Dropdown menu panel content Bindings: `items: MazDropdownMenuItem[]` (Array of menu items passed via the items prop), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown).
- `#prepend-menu`: Prepend to the list of menu items Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `toggle: () => void` (Function to toggle the dropdown).
- `#menuitem`: Menu item component Bindings: `item: MazDropdownMenuItem` (Individual menu item object with properties like label, href, onClick, etc.), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown).
- `#menuitem-label`: Label content for menu item Bindings: `item: MazDropdownMenuItem` (Individual menu item object containing label and other properties), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown).
- `#append-menu`: Append to the list of menu items Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `toggle: () => void` (Function to toggle the dropdown).
