---
title: "MazBtnGroup"
description: "MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-btn-group"
---

# MazBtnGroup

> MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color.

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

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

## Basic usage with items

Use the `items` prop to quickly create a button group from an array of button configurations.

```vue
<template>
  <MazBtnGroup :items="items" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'

const items: MazButtonGroupOption[] = [
  { text: 'Day' },
  { text: 'Week', active: true },
  { text: 'Month' },
]
</script>
```

## Slot-based usage

Use the default slot to pass `MazBtn` components directly for full control over each button.

```vue
<template>
  <MazBtnGroup>
    <MazBtn>Edit</MazBtn>
    <MazBtn :active="true">Save</MazBtn>
    <MazBtn>Delete</MazBtn>
  </MazBtnGroup>
</template>

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

## Orientation

Use the `orientation` prop to arrange buttons horizontally (`row`) or vertically (`col`).

```vue
<template>
  <MazBtnGroup :items="items" orientation="row" />
  <MazBtnGroup :items="items" orientation="col" />
</template>
```

## Sizes

Use the `size` prop to apply a size to all buttons in the group.

```vue
<template>
  <MazBtnGroup :items="items" size="mini" />
  <MazBtnGroup :items="items" size="xs" />
  <MazBtnGroup :items="items" size="sm" />
  <MazBtnGroup :items="items" size="md" />
  <MazBtnGroup :items="items" size="lg" />
  <MazBtnGroup :items="items" size="xl" />
</template>
```

## Colors

Use the `color` prop to apply a color to all buttons in the group. Neutral colors (`surface`, `container`) are supported, see the [surface vs container tip](./maz-btn.md#colors).

```vue
<template>
  <MazBtnGroup :items="items" color="primary" />
  <MazBtnGroup :items="items" color="secondary" />
  <MazBtnGroup :items="items" color="info" />
  <MazBtnGroup :items="items" color="success" />
  <MazBtnGroup :items="items" color="warning" />
  <MazBtnGroup :items="items" color="destructive" />
  <MazBtnGroup :items="items" color="surface" />
  <MazBtnGroup :items="items" color="container" />
</template>
```

## Button variants

Use the `outlined` or `pastel` properties on individual buttons or apply different variants to buttons in the group.

### Outlined

```vue
<template>
  <MazBtnGroup :items="items" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'

const items: MazButtonGroupOption[] = [
  { text: 'Day', outlined: true },
  { text: 'Week', outlined: true },
  { text: 'Month', outlined: true },
]
</script>
```

### Pastel

```vue
<template>
  <MazBtnGroup :items="items" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'

const items: MazButtonGroupOption[] = [
  { text: 'Day', pastel: true },
  { text: 'Week', pastel: true },
  { text: 'Month', pastel: true },
]
</script>
```

### Slot-based variants

```vue
<template>
  <MazBtnGroup>
    <MazBtn outlined>Edit</MazBtn>
    <MazBtn outlined>Save</MazBtn>
    <MazBtn outlined>Delete</MazBtn>
  </MazBtnGroup>

  <MazBtnGroup>
    <MazBtn pastel>Edit</MazBtn>
    <MazBtn pastel>Save</MazBtn>
    <MazBtn pastel>Delete</MazBtn>
  </MazBtnGroup>
</template>
```

## Click handlers

Add click handlers to buttons using the `onClick` property in items.

```vue
<template>
  <MazBtnGroup :items="items" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
import { useToast } from 'maz-ui/composables/useToast'

const toast = useToast()

const items: MazButtonGroupOption[] = [
  { text: 'Toast', onClick: () => toast.info('Clicked Toast!') },
  { text: 'Console', onClick: () => console.log('Clicked Console!') },
]
</script>
```

## With icons

Use the `startIcon` or `endIcon` properties to add icons to buttons.

```vue
<template>
  <MazBtnGroup :items="items" />
  <MazBtnGroup :items="iconOnlyItems" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
import { MazArrowLeft } from '@maz-ui/icons/raw/MazArrowLeft'
import { MazArrowRight } from '@maz-ui/icons/raw/MazArrowRight'

const items: MazButtonGroupOption[] = [
  { text: 'Previous', startIcon: MazArrowLeft, active: true },
  { text: 'Next', endIcon: MazArrowRight },
]

const iconOnlyItems: MazButtonGroupOption[] = [
  { icon: MazBars3, color: 'transparent', outlined: true, active: true },
  { icon: MazSquares2x2, color: 'transparent', outlined: true },
]
</script>
```

## With links

Use the `href` or `to` properties to create link buttons.

```vue
<template>
  <MazBtnGroup :items="items" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'

const items: MazButtonGroupOption[] = [
  { text: 'External Link', href: 'https://maz-ui.com', target: '_blank' },
  { text: 'Router Link', to: { path: '/components/maz-btn' } },
]
</script>
```

## Mixed button styles

Combine different button styles within the same group.

```vue
<template>
  <MazBtnGroup :items="items" />
</template>

<script lang="ts" setup>
import MazBtnGroup from 'maz-ui/components/MazBtnGroup'
import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'

const items: MazButtonGroupOption[] = [
  { text: 'Primary', color: 'primary' },
  { text: 'Success', color: 'success' },
  { text: 'Warning', color: 'warning', outlined: true },
  { text: 'Destructive', color: 'destructive', pastel: true },
]
</script>
```

## Types

### MazButtonGroupOption

```ts
import type { MazBtnProps } from 'maz-ui/components/MazBtn'
import type { RouteLocationRaw } from 'vue-router'

interface MazButtonGroupOption extends Omit<MazBtnProps, 'block'> {
  /** The text of the button */
  text: string
  /** Click handler for the button */
  onClick?: () => void
  /** The href for anchor links */
  href?: string
  /** The route for router-link */
  to?: RouteLocationRaw
}
```

### MazButtonGroupProps

```ts
interface MazButtonGroupProps {
  /**
   * The items for the button group (optional when using slot-based approach)
   * @default undefined
   */
  items?: MazButtonGroupOption[]
  /**
   * The orientation of the button group
   * @values 'row' | 'col'
   * @default 'row'
   */
  orientation?: 'row' | 'col'
  /**
   * The size of all buttons (only applies to props-based buttons)
   * @default 'md'
   */
  size?: 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  /**
   * The color of all buttons (only applies to props-based buttons)
   * @default 'primary'
   */
  color?: 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'destructive' | 'transparent' | 'contrast' | 'accent' | 'surface' | 'container'
}
```

## MazBtnGroup API

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

### Props

- `items` (`MazButtonGroupOption[]`): The items for the button group (optional when using slot-based approach).
- `orientation` (`"col" | "row"`, default: `"row"`): The orientation of the button group.
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of all buttons (only applies to props-based buttons).
- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | "surface" | "container"`, default: `"primary"`): The color of all buttons (only applies to props-based buttons).
- `rounded-size` (`MazRoundedSize`, default: `'lg'`): The rounded size of the buttons.
- `outlined` (`boolean`, default: `false`): The outlined state of the buttons.
- `pastel` (`boolean`, default: `false`): The pastel state of the buttons.
- `loading` (`boolean`, default: `false`): The loading state of the buttons.
- `disabled` (`boolean`, default: `false`): The disabled state of the buttons.

### Slots

- `#default`: Slot for passing MazBtn components directly
- `#button-{index}`: One slot per `index`: `#button-<index>`.
