MazDropdown

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

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>

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

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

html

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

html

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

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

vue

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

TIP

This component uses MazBtn has a menu button, so it inherits all its props

html

<MazDropdown
  color="primary"
  fab
  pastel
  :chevron="false"
  icon="bars-3"
  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"
/>

Custom slots

You can provide a template to replace the default dropdown panel

View code

html

<MazDropdown>
  Customized dropdown panel

  <template #dropdown>
    <div class="maz-grid maz-grid-cols-3 maz-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

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="maz-flex maz-items-center maz-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

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="maz-border maz-border-solid maz-border-divider-400 maz-p-2 hover:maz-bg-surface-400" tabindex="-1">
      HTMLButtonElement: isOpen {{ isOpen }}
    </button>
  </template>
</MazDropdown>

Open programmatically

isOpen: false

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

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

Props

Name	Description	Type	Required	Default	Possible values
model-value	`v-model` Controls whether the dropdown menu is open	`boolean`	No	`false`	-
style	Inline styles to apply to the component root element	`HTMLAttributes['style']`	No	`undefined`	-
class	CSS classes to apply to the component root element	`HTMLAttributes['class']`	No	`undefined`	-
items	Menu items to display in the dropdown Each item can be either a link (with href/to properties) or an action (with onClick function) Example: `[ { label: 'Profile', href: '/profile' }, { label: 'Settings', onClick: () => console.log('Settings clicked') } ]`	`MazDropdownMenuItem[]`	No	`[]`	-
id	Unique identifier for the dropdown component	`string`	No	`undefined`	-
trigger	Determines how the dropdown should be triggered	`MazPopoverProps['trigger']`	No	`adaptive`	`click, hover, manual, adaptive`
color	Color theme for the dropdown button	`MazColor`	No	`transparent`	`primary, secondary, info, success, warning, destructive, transparent, contrast, accent`
position	Position of the menu relative to trigger	`Native type`	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 menu relative to trigger when auto position is used	`Native type`	No	`bottom-start`	`auto, top, bottom, left, right, top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end`
close-on-click	Controls whether the dropdown menu closes when a menu item is clicked	`boolean`	No	`true`	-
disabled	Disables the dropdown functionality	`boolean`	No	`false`	-
chevron	Controls whether to show the chevron icon in the trigger button	`boolean`	No	`true`	-
screen-reader-description	Accessible description for screen readers describing the dropdown functionality If not provided, the default translation of MazUiTranslations plugin will be used	`string`	No	`MazUiTranslationsSchema['dropdown']['screenReaderDescription']`	-
menu-panel-class	Additional CSS classes to apply to the dropdown menu panel Useful for customizing the dropdown appearance (background, border, etc.)	`HTMLAttributes['class']`	No	`undefined`	-
menu-panel-style	Inline styles to apply to the dropdown menu panel Useful for custom styling. You may use `!important` to override default styles	`HTMLAttributes['style']`	No	`undefined`	-
block	Makes the dropdown button expand to full width of its container	`boolean`	No	`false`	-
dropdown-icon	Icon to use instead of the default chevron for the dropdown indicator Can be either an icon name string or a Vue component Example: `'arrow-down'`	`string \| IconComponent`	No	`undefined`	-
dropdown-icon-animation	Controls whether the dropdown icon rotates when the dropdown is opened	`boolean`	No	`true`	-
size	Size of the dropdown button	`MazSize`	No	`md`	`mini, xs, sm, md, lg, xl`
transition	Transition to use when the dropdown is opened or closed	`MazPopoverProps['transition']`	No	`scale-pop`	`scale-pop' \| 'scale-fade' \| string`

Events

Event name	Properties	Description
menuitem-clicked	event `Event` - The native click event from the menu item interaction	Emitted when a menu item is clicked
update:model-value	value `boolean` - The new open state (true when opened, false when closed)	Emitted when the dropdown open state changes

Slots

Name	Description	Bindings
screen-reader-description	description for screen readers (hidden from visual display)
trigger	trigger element for the dropdown	is-open `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	is-open `boolean` - Current state of the dropdown (true when open, false when closed)
dropdown	Dropdown menu panel content	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 is-open `boolean` - Current state of the dropdown (true when open, false when closed) toggle `() => void` - Function to toggle the dropdown
menuitem	Menu item component	item `MenuItem` - 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 is-open `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	item `MenuItem` - Individual menu item object containing label and other properties open `() => void` - Function to open the dropdown close `() => void` - Function to close the dropdown is-open `boolean` - Current state of the dropdown (true when open, false when closed) toggle `() => void` - Function to toggle the dropdown

MazDropdown ​

Basic usage ​

Open dropdown with adaptive trigger ​

Open dropdown only on click ​

Open dropdown only on hover ​

Custom dropdown icon ​

Custom dropdown main button without chevron icon ​

Custom slots ​

Custom dropdown panel ​

Custom menuitem labels ​

Custom control triggered element ​

Open programmatically ​

Position ​

Types ​

MazDropdownMenuItem ​

Props ​

Events ​

Slots ​

MazDropdown

Basic usage

Open dropdown with adaptive trigger

Open dropdown only on click

Open dropdown only on hover

Custom dropdown icon

Custom dropdown main button without chevron icon

Custom slots

Custom dropdown panel

Custom menuitem labels

Custom control triggered element

Open programmatically

Position

Types

MazDropdownMenuItem

Props

Events

Slots