Actions

ButtonGroup

Visual and semantic grouping of related buttons that share a single accessible label and present as one connected control.

import { ButtonGroup } from '@lostgradient/cinder';
actiongrouping
01

Overview

Reference usage

Clusters related action buttons into a unified visual group with shared borders.

Usage

svelte 
<script lang="ts">
  import { Button } from '@lostgradient/cinder';
  import { ButtonGroup } from '@lostgradient/cinder';
</script>

<ButtonGroup label="Document actions">
  <Button variant="secondary">Save</Button>
  <Button variant="secondary">Duplicate</Button>
  <Button variant="secondary">Archive</Button>
</ButtonGroup>

Input with an attached Button

An Input can be the first member of a group, with a Button as the trailing part of the field. The pair shares one border, one height and the outer corners: the Input and the Button take their height from the same step of the shared control height scale, so give both the same size and they match at sm, md and lg.

svelte 
<script lang="ts">
  import { Button, ButtonGroup, FormField, Input } from '@lostgradient/cinder';

  let key = $state('');
</script>

<FormField id="api-key" label="API key">
  <ButtonGroup ariaLabelledby="api-key-label">
    <Input id="api-key" bind:value={key} />
    <Button variant="secondary">Test a key</Button>
  </ButtonGroup>
</FormField>

Keep the label, description and error outside the group, so nothing but the control sits beside the Button: label the field with an enclosing FormField (as above) or a visually hidden label (labelVisible={false}), and put any description or error on the FormField. Use this for a field the user submits with the button (Test a key, Add a tag). A field that updates as the user types needs no button. A group that holds a field is horizontal only.

Live preview

Basic button group

02

When to use

Use when
  • Clustering related actions such as align-left/center/right that read as a single toolset.
  • Visually joining multiple buttons into a single segmented bar without implying selection.
  • Pairing an Input with a trailing Button that shares its border, height and corners.
Avoid when
  • Selecting exactly one option from a fixed set — use segmented-control instead.
  • Rendering a single button — use button on its own.
03

Examples

Basic button group

Horizontal layout container with border-collapsed buttons. Use consistent variants across children.

Input with an attached button

An Input as the first member and a Button as the trailing part of the field share one border, height and set of corners. Give both the same size.

Right-to-left (RTL)

Logical properties automatically flip collapsed borders and outer corner rounding when the writing direction is RTL.

Split button composition

A primary action button paired with a dropdown for related secondary actions. This is composition — ButtonGroup does no split-button work itself.

Vertical button group

Vertically stacked buttons with collapsed borders.

04

Props

Props for button-group
Name
Type
Default
Description
label required text Inline accessible name for the group, applied as aria-label. Provide exactly one of label or ariaLabelledby.
ariaLabelledby text The id of a visible heading element that already names the group, applied as aria-labelledby. Provide exactly one of label or ariaLabelledby.
orientation 'horizontal' | 'vertical' 'horizontal' Orientation of the visual collapse. Default: 'horizontal'.
children required snippet Buttons (or split-button compositions) to render inside the group.