Button Group

Accessible, unstyled adjacent action group with optional toolbar roving focus.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { ButtonGroup, ButtonGroupItem } from "@vizejs/ui/button-group";

Or copy the source into your project with vize lib pull button-group (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Text-formatting toolbar with arrow-key roving focus and one disabled action. -->
<script setup lang="ts">
import { ref } from "vue";

import { ButtonGroup, ButtonGroupItem } from "@vizejs/ui/button-group";

const lastAction = ref("none");
</script>

<template>
  <div>
    <ButtonGroup
      role="toolbar"
      aria-label="Text formatting"
      @press="(value) => (lastAction = value)"
    >
      <ButtonGroupItem value="bold">Bold</ButtonGroupItem>
      <ButtonGroupItem value="italic">Italic</ButtonGroupItem>
      <ButtonGroupItem value="underline">Underline</ButtonGroupItem>
      <ButtonGroupItem value="strikethrough" disabled>Strikethrough</ButtonGroupItem>
    </ButtonGroup>
    <output>Last action: {{ lastAction }}</output>
  </div>
</template>

API

ButtonGroup

Source: src/families/actions/button-group/button-group.vue

Props

Events

Slots

Exposed

ButtonGroupItem

Source: src/families/actions/button-group/button-group-item.vue

Props

Events

Slots

Exposed

Behavior

Contract

ButtonGroup is a headless compound primitive for adjacent actions such as button bars, editor toolbars, card action rows, and destructive-confirmation clusters. It owns no selection model and emits no visual CSS. Consumers style through data-vize-ui, data-state, data-disabled, data-orientation, data-role, and part attributes.

role="group" preserves the native tab order by default. role="toolbar" defaults to a single tab stop with arrow-key movement because that is the WAI-ARIA toolbar expectation. Consumers may explicitly set rovingFocus on either role.

Items require a unique string value so item-level and group-level press events, activeValue, roving tabindex, and focusValue() stay stable across polymorphic rendering, slot changes, and DOM reordering. Duplicate values throw VIZE_UI_BUTTON_GROUP_VALUE_DUPLICATE during registration or reactive value changes before more than one item can own the active tab stop.