Button Group

A container that groups related buttons together with consistent styling.

Accessibility

The ButtonGroup component wraps buttons in a container with role="group" (inside its Shadow DOM) to indicate a set of related controls. You can add an aria-label attribute to the <c-button-group> element to provide context for screen reader users.

<c-button-group aria-label="Text formatting">
  <c-button variant="outline">Bold</c-button>
  <c-button variant="outline">Italic</c-button>
  <c-button variant="outline">Underline</c-button>
</c-button-group>

Examples

Default

Button 1 Button 2 Button 3 
<c-button-group>
  <c-button variant="outline">Button 1</c-button>
  <c-button variant="outline">Button 2</c-button>
  <c-button variant="outline">Button 3</c-button>
</c-button-group>

Orientation

Set the orientation prop to change the button group layout.

<c-button-group orientation="vertical">
  <c-button variant="outline" size="icon">
    <c-lucide-icon icon="plus" size="16"></c-lucide-icon>
  </c-button>
  <c-button variant="outline" size="icon">
    <c-lucide-icon icon="minus" size="16"></c-lucide-icon>
  </c-button>
</c-button-group>

Size

Control the size of buttons using the size prop on individual buttons.

Small Small Small Default Default Default Large Large Large 
<div class="flex flex-col gap-4">
  <c-button-group>
    <c-button variant="outline" size="sm">Small</c-button>
    <c-button variant="outline" size="sm">Small</c-button>
    <c-button variant="outline" size="sm">Small</c-button>
  </c-button-group>
  <c-button-group>
    <c-button variant="outline">Default</c-button>
    <c-button variant="outline">Default</c-button>
    <c-button variant="outline">Default</c-button>
  </c-button-group>
  <c-button-group>
    <c-button variant="outline" size="lg">Large</c-button>
    <c-button variant="outline" size="lg">Large</c-button>
    <c-button variant="outline" size="lg">Large</c-button>
  </c-button-group>
</div>

Nested

Nest ButtonGroup components to create button groups with spacing.

1 2 3 4 5 
<c-button-group>
  <c-button-group>
    <c-button variant="outline" size="sm">1</c-button>
    <c-button variant="outline" size="sm">2</c-button>
    <c-button variant="outline" size="sm">3</c-button>
    <c-button variant="outline" size="sm">4</c-button>
    <c-button variant="outline" size="sm">5</c-button>
  </c-button-group>
  <c-button-group>
    <c-button variant="outline" size="icon-sm" aria-label="Previous">
      <c-lucide-icon icon="arrow-left" size="14"></c-lucide-icon>
    </c-button>
    <c-button variant="outline" size="icon-sm" aria-label="Next">
      <c-lucide-icon icon="arrow-right" size="14"></c-lucide-icon>
    </c-button>
  </c-button-group>
</c-button-group>

Separator

The ButtonGroupSeparator component visually divides buttons within a group.

Buttons with variant outline do not need a separator since they have a border. For other variants, a separator is recommended to improve the visual hierarchy.

Button 1 Button 2 Button 3 
<c-button-group>
  <c-button variant="secondary">Button 1</c-button>
  <c-button-group-separator></c-button-group-separator>
  <c-button variant="secondary">Button 2</c-button>
  <c-button-group-separator></c-button-group-separator>
  <c-button variant="secondary">Button 3</c-button>
</c-button-group>

Split

Create a split button group by adding two buttons separated by a ButtonGroupSeparator.

Save 
<c-button-group>
  <c-button variant="secondary">Save</c-button>
  <c-button-group-separator></c-button-group-separator>
  <c-button variant="secondary" size="icon">
    <c-lucide-icon icon="chevron-down" size="16"></c-lucide-icon>
  </c-button>
</c-button-group>

Input

Wrap an Input component with buttons.

<c-button-group button-group-classes="max-w-sm">
  <c-button variant="outline">
    <c-lucide-icon icon="search" size="16"></c-lucide-icon>
  </c-button>
  <c-input
    placeholder="Search..."
    input-classes="rounded-none border-x-0"
  ></c-input>
  <c-button variant="outline">
    <c-lucide-icon icon="x" size="16"></c-lucide-icon>
  </c-button>
</c-button-group>

Create a split button group with a DropdownMenu component.

Actions
Edit Duplicate Delete 
<c-button-group>
  <c-button variant="outline">Actions</c-button>
  <c-button-group-separator></c-button-group-separator>
  <c-dropdown-menu>
    <c-button variant="outline" size="icon" slot="trigger">
      <c-lucide-icon icon="chevron-down" size="16"></c-lucide-icon>
    </c-button>
    <div slot="content">
      <c-dropdown-menu-item>Edit</c-dropdown-menu-item>
      <c-dropdown-menu-item>Duplicate</c-dropdown-menu-item>
      <c-dropdown-menu-separator></c-dropdown-menu-separator>
      <c-dropdown-menu-item>Delete</c-dropdown-menu-item>
    </div>
  </c-dropdown-menu>
</c-button-group>

Text

Use ButtonGroupText to add a text label within a button group.

Pages Filter Status Priority View Grid List 
<!-- Default -->
<c-button-group>
  <c-button-group-text>Pages</c-button-group-text>
  <c-button variant="outline" size="icon">
    <c-lucide-icon icon="chevron-left" size="16"></c-lucide-icon>
  </c-button>
  <c-button variant="outline" size="icon">
    <c-lucide-icon icon="chevron-right" size="16"></c-lucide-icon>
  </c-button>
</c-button-group>

<!-- Text with buttons -->
<c-button-group>
  <c-button-group-text>Filter</c-button-group-text>
  <c-button variant="outline">Status</c-button>
  <c-button variant="outline">Priority</c-button>
</c-button-group>

<!-- Text with small buttons -->
<c-button-group>
  <c-button-group-text>View</c-button-group-text>
  <c-button variant="outline" size="sm">Grid</c-button>
  <c-button variant="outline" size="sm">List</c-button>
</c-button-group>

API Reference

ButtonGroup

The root container for grouping buttons.

Prop Type Default Description
orientation 'horizontal' | 'vertical' 'horizontal' -
button-group-classes string - Additional CSS classes for the element

ButtonGroupText

Text label within a button group.

Prop Type Default Description
button-group-text-classes string - Additional CSS classes for the element

ButtonGroupSeparator

Divider between buttons in a group.

Prop Type Default Description
button-group-separator-classes string - Additional CSS classes for the element