MazBtnDropdown
MazBtnDropdown is a split button. The main action is on the left, and its variants are in a menu behind the chevron on the right ("Save" and "Save as draft", "Merge" and "Squash and merge"). It takes the visual props of MazBtn and the menu of MazDropdown.
Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started
MazBtnDropdown or MazDropdown?
- MazBtnDropdown: two buttons. A click on the main action runs it, the chevron opens the menu of its variants.
- MazDropdown: one button, whose only role is to open the menu (a "More" or "Account" menu).
Basic usage
The default slot is the content of the main action, which emits click. The items are the variants, listed in the menu of the chevron: they take the same options as the items of MazDropdown (label, onClick, href, to, target, color, disabled...). The menu closes when an item is clicked.
menu-label is required: it is the accessible name of the chevron, also shown as its native tooltip.
Last action: none
<script lang="ts" setup>
import type { MazBtnDropdownProps } from 'maz-ui/components/MazBtnDropdown'
import MazBtnDropdown from 'maz-ui/components/MazBtnDropdown'
import { ref } from 'vue'
const lastAction = ref('none')
const items: MazBtnDropdownProps['items'] = [
{ label: 'Save as draft', onClick: () => { lastAction.value = 'Save as draft' } },
{ label: 'Save and publish', onClick: () => { lastAction.value = 'Save and publish' } },
{ label: 'Delete', color: 'destructive', onClick: () => { lastAction.value = 'Delete' } },
]
</script>
<template>
<MazBtnDropdown :items="items" menu-label="Other save options" @click="lastAction = 'Save'">
Save
</MazBtnDropdown>
</template>Without items (or with an empty array), the chevron is hidden and the component is a simple button with its rounded corners: handy when the variants depend on the context.
Colors and styles
color, outlined and pastel apply to both parts.
<template>
<MazBtnDropdown :items="items" color="secondary" menu-label="Other save options">
Save
</MazBtnDropdown>
<MazBtnDropdown :items="items" outlined menu-label="Other save options">
Outlined
</MazBtnDropdown>
<MazBtnDropdown :items="items" pastel menu-label="Other save options">
Pastel
</MazBtnDropdown>
<!-- Only the outer corners are rounded -->
<MazBtnDropdown :items="items" color="contrast" rounded-size="full" menu-label="Other save options">
Rounded full
</MazBtnDropdown>
</template>Sizes
size applies to both parts, items-size to the items of the menu (sm by default).
<template>
<MazBtnDropdown :items="items" size="mini" menu-label="Other save options">
mini
</MazBtnDropdown>
<MazBtnDropdown :items="items" size="xl" items-size="md" menu-label="Other save options">
xl
</MazBtnDropdown>
</template>Icon and full width
start-icon adds an icon before the content of the main action. With block, the component takes the full width of its container: the main action grows, the chevron keeps its size.
<script lang="ts" setup>
import { MazArrowDownTray } from '@maz-ui/icons/raw/MazArrowDownTray'
import MazBtnDropdown from 'maz-ui/components/MazBtnDropdown'
const items = [
{ label: 'Download CSV', onClick: () => {} },
{ label: 'Download XLSX', onClick: () => {} },
]
</script>
<template>
<MazBtnDropdown :items="items" :start-icon="MazArrowDownTray" block menu-label="Other download formats">
Download PDF
</MazBtnDropdown>
</template>Tooltip
tooltip adds a tooltip to the main action only: the chevron keeps its native tooltip, from menu-label. It takes a text, or the options of the v-tooltip directive (text, position, color...).
<template>
<MazBtnDropdown :items="items" tooltip="Save the document" menu-label="Other save options">
Save
</MazBtnDropdown>
<MazBtnDropdown
:items="items"
:tooltip="{ text: 'Publish to production', position: 'bottom', color: 'warning' }"
color="warning"
menu-label="Other publish options"
>
Publish
</MazBtnDropdown>
</template>Trigger and position
By default, the menu opens on click of the chevron. Set trigger to hover, or to adaptive (hover on desktop, click on touch devices). position places the menu relative to the chevron (bottom-end by default).
<template>
<MazBtnDropdown :items="items" trigger="hover" menu-label="Other save options">
Hover
</MazBtnDropdown>
<MazBtnDropdown :items="items" trigger="adaptive" position="top-start" menu-label="Other save options">
Adaptive, on top
</MazBtnDropdown>
</template>Loading and disabled states
loadingshows the loader of the main action only.disableddisables both parts.action-disableddisables only the main action, the menu stays usable: the main target is not available, but its variants are.menu-disableddisables only the chevron.
<template>
<MazBtnDropdown :items="items" loading menu-label="Other save options">
Loading
</MazBtnDropdown>
<MazBtnDropdown :items="items" disabled menu-label="Other save options">
Disabled
</MazBtnDropdown>
<MazBtnDropdown :items="items" action-disabled menu-label="Other save options">
Action disabled
</MazBtnDropdown>
<MazBtnDropdown :items="items" menu-disabled menu-label="Other save options">
Menu disabled
</MazBtnDropdown>
</template>In a form
Set type="submit" to submit a form with the main action. The chevron never submits the form.
<template>
<form @submit.prevent="save">
<MazInput v-model="title" label="Title" />
<MazBtnDropdown type="submit" :items="items" menu-label="Other save options">
Save
</MazBtnDropdown>
</form>
</template>Custom item labels
The menuitem-label slot replaces the label of each item. It receives { item }.
<script lang="ts" setup>
import MazBtnDropdown from 'maz-ui/components/MazBtnDropdown'
const items = [
{ label: 'Save as draft', shortcut: '⌘ D', onClick: () => {} },
{ label: 'Save and publish', shortcut: '⌘ ⇧ S', onClick: () => {} },
]
</script>
<template>
<MazBtnDropdown :items="items" menu-label="Other save options">
Save
<template #menuitem-label="{ item }">
<span class="flex w-full items-center justify-between gap-4">
{{ item.label }}
<kbd class="text-xs text-muted">{{ item.shortcut }}</kbd>
</span>
</template>
</MazBtnDropdown>
</template>Global defaults
size and roundedSize can be set for every instance with the global defaults, under the MazBtnDropdown key (or global for every component).
app.use(MazUi, {
defaults: {
MazBtnDropdown: { size: 'sm', roundedSize: 'full' },
},
})Accessibility
- The two parts are wrapped in an element with
role="group". Name the group witharia-labelwhen the page has several split buttons. - The chevron is a real button named by
menu-label, witharia-haspopup="menu"andaria-expanded. Givemenu-labelin the language of the page and describe the variants ("Other save options"), not the icon ("Chevron"). - The menu is the one of MazDropdown: keyboard navigation with the arrow keys,
Escapeto close it.
Props
| Name | Description | Type | Required | Default | Possible values |
|---|---|---|---|---|---|
| items | Variants of the main action, listed in the menu of the chevron; without items, the chevron is hidden | MazDropdownMenuItem[] | No | [] | - |
| menu-label | Accessible name of the chevron, also shown as its native tooltip (e.g. "Other versions") | string | Yes | - | - |
| size | Size of both parts | "xs" | "sm" | "md" | "lg" | "xl" | "mini" | No | 'md' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'mini' |
| color | Color of both parts | "primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | "surface" | "container" | No | "primary" | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent' | 'surface' | 'container' |
| rounded-size | Size of the rounded of the outer corners (the inner ones stay square) | MazRoundedSize | No | 'md' | 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' |
| pastel | If true, both parts have a pastel color | boolean | No | false | - |
| outlined | If true, both parts have the "border" style | boolean | No | false | - |
| loading | Enable the loader of the main action | boolean | No | false | - |
| disabled | Disable both parts | boolean | No | false | - |
| action-disabled | Disable only the main action: the menu stays usable (e.g. the main target is not available but its variants are) | boolean | No | false | - |
| menu-disabled | Disable only the menu | boolean | No | false | - |
| items-size | Size of the menu items | "xs" | "sm" | "md" | "lg" | "xl" | "mini" | No | "sm" | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'mini' |
| position | Position of the menu relative to the chevron | MazPopoverPosition | No | "bottom-end" | 'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' |
| trigger | How the menu opens: on click of the chevron, on hover, or adaptive (hover on desktop, click on touch devices) | MazPopoverTrigger | No | "click" | 'click' | 'hover' | 'manual' | 'adaptive' |
| type | Native type of the main action (submit to submit a form) | "submit" | "reset" | "button" | No | "button" | 'submit' | 'reset' | 'button' |
| start-icon | Icon displayed before the content of the main action | MazIconLike | No | - | - |
| block | If true, the component takes the full width of its container: the main action grows, the chevron keeps its size | boolean | No | false | - |
| tooltip | Tooltip of the main action only (the chevron keeps its native title): a text, or the options of the v-tooltip directive ({ text, position, color... }) | VTooltipBindingValue | No | - | - |
Events
| Event name | Payload | Description |
|---|---|---|
| click | event: MouseEvent | Emitted when the main action is clicked |
Slots
| Name | Description | Bindings |
|---|---|---|
| default | The content of the main action | - |
| menuitem-label | The label of a menu item | item MazDropdownMenuItem - the menu item |