Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

ButtonGroup

Groups related controls horizontally or vertically without changing their behavior.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add button-group

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import ButtonGroup from './components/ui/button-group/ButtonGroup.vue'
</script>

<template>
  <ButtonGroup aria-label="Text alignment">
    <Button variant="outline">Left</Button>
    <Button variant="outline">Center</Button>
    <Button variant="outline">Right</Button>
  </ButtonGroup>
</template>

The root has role="group". Name it with aria-label or aria-labelledby when nearby text does not already identify the group; each child retains its own keyboard, disabled, and form behavior.

When to use it

Related commands

Visually join commands such as previous and next without changing their native button behavior.

Spaced group

Set attached to false when related actions need separate outlines.

More examples

History navigation

Each button keeps its own disabled state.

History navigation
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import ButtonGroup from './components/ui/button-group/ButtonGroup.vue'

defineProps<{ canUndo: boolean; canRedo: boolean }>()
</script>
<template>
  <ButtonGroup aria-label="History">
    <Button variant="outline" :disabled="!canUndo" @click="$emit('undo')">Undo</Button>
    <Button variant="outline" :disabled="!canRedo" @click="$emit('redo')">Redo</Button>
  </ButtonGroup>
</template>

Vertical actions

Orientation changes the visual stack, not the children’s behavior.

Vertical actions
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import ButtonGroup from './components/ui/button-group/ButtonGroup.vue'
</script>
<template>
  <ButtonGroup orientation="vertical" :attached="false" aria-label="Export formats">
    <Button variant="outline" @click="$emit('export', 'pdf')">PDF</Button>
    <Button variant="outline" @click="$emit('export', 'csv')">CSV</Button>
  </ButtonGroup>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

ButtonGroup

Complete API for ButtonGroup
NameType or signatureDefaultWhat it does
orientationprop"horizontal" | "vertical" | undefined"horizontal"Arrange items horizontally or vertically.
attachedpropboolean | undefinedtrueJoin neighboring controls into one visual group.
defaultslot() => unknownRequiredContent shown inside ButtonGroup.
Public type definitions
Public types
// packages/frameworks/vue/components/button-group/types.ts
// ------- TYPES -------

export interface ButtonGroupProps {
  orientation?: 'horizontal' | 'vertical'
  attached?: boolean
}

Implementation notes

  • ButtonGroup provides role="group" and visual joins; it does not coordinate selection.
  • Set attached=false to retain space and independent corners between controls.

Accessibility and localization

  • Name the group when nearby text does not identify its purpose.
  • Every child remains an independent keyboard stop with its own action.

Source contract and editing guidance