Button Group

<loomi-button-group> and <loomi-button-group-item> — a horizontal row of segmented toggle buttons with shared sizing, radius, icons, colors, outline mode, and disabled states.

1
npm install @loomidev/button-group lit

1
import "@loomidev/button-group";

Basic Usage

Place <loomi-button-group-item> elements inside a group. One item can be marked selected for the initial state.

1
<loomi-button-group>
2
  <loomi-button-group-item label="Day" value="day" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Week" value="week"></loomi-button-group-item>
4
  <loomi-button-group-item label="Month" value="month"></loomi-button-group-item>
5
</loomi-button-group>

Listen for selection changes on the group:

1
<loomi-button-group id="range">
2
  <loomi-button-group-item label="Day" value="day" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Week" value="week"></loomi-button-group-item>
4
</loomi-button-group>
5

6
<script type="module">
7
  document.querySelector("#range").addEventListener("loomi-button-group-change", (event) => {
8
    console.log(event.detail.value);
9
  });
10
</script>

Icons

Use the same built-in icon names as <loomi-button>. Set icon-right to place the icon after the label.

1
<loomi-button-group>
2
  <loomi-button-group-item label="List" value="list" icon="list" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Grid" value="grid" icon="grid-2x2"></loomi-button-group-item>
4
</loomi-button-group>

Icon-only items work too. Set icon-only on the group when every item should be compact, or on one item when only that button should hide its label.

1
<loomi-button-group color="primary" icon-only aria-label="Text formatting">
2
  <loomi-button-group-item label="Bold" value="bold" icon="bold" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Italic" value="italic" icon="italic"></loomi-button-group-item>
4
</loomi-button-group>

Sizes, Radius, Outline, and Colors

size accepts tiny, small, regular (default), medium, and big. radius accepts the same values as <loomi-button>: none, small, medium (default), and full. The segmented bar is shrink-wrapped, so it ends with the last button instead of filling the parent width.

The selected item uses the same surface fill, accent text, and subtle shadow as <loomi-tabs tab-style="system">. color accepts any Loomi color name and tints the selected text plus focus ring. Add outline for a transparent, outline-only variant.

1
<loomi-button-group size="small" radius="full" color="success">
2
  <loomi-button-group-item label="Left" value="left" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Right" value="right"></loomi-button-group-item>
4
</loomi-button-group>

1
<loomi-button-group outline radius="small" color="error">
2
  <loomi-button-group-item label="Open" value="open" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Closed" value="closed"></loomi-button-group-item>
4
</loomi-button-group>

Disabled States

Disable a single item with disabled on <loomi-button-group-item>, or disable the entire group with disabled on <loomi-button-group>.

1
<loomi-button-group disabled>
2
  <loomi-button-group-item label="Day" value="day" selected></loomi-button-group-item>
3
  <loomi-button-group-item label="Week" value="week"></loomi-button-group-item>
4
</loomi-button-group>

Accessibility

Supports keyboard focus with visible :focus-visible styling on each button.
Icon-only items should provide label or aria-label so the button still has an accessible name.

For the library-wide baseline, see Foundations — Accessibility.

Responsive behavior

For dense layouts, let the component keep its natural shrink-wrapped width and give the surrounding layout room to scroll or wrap. For long labels or user-provided content, prefer concise text instead of fixed pixel assumptions.

For the shared container and viewport rules, see Foundations — Responsive behavior.

Dark mode

For theme activation, token overrides, and contrast guidance, see Foundations — Dark mode.

Attributes

`<loomi-button-group>`

Attribute	Default	Description
`color`	`primary`	Accent color for the selected item text and focus ring. Accepts any Loomi color name.
`size`	`regular`	Button size. `tiny` \| `small` \| `regular` \| `medium` \| `big`.
`radius`	`medium`	Bar corner radius. `none` \| `small` \| `medium` \| `full`.
`outline`	`false`	Outline-only treatment: transparent track and selected item outline. (boolean)
`icon-only`	`false`	Hide every item label visually and render square icon buttons. (boolean)
`aria-label`	(blank)	Accessible label for the internal `role="group"` wrapper.
`disabled`	`false`	Disable every item in the group. (boolean)

`<loomi-button-group-item>`

Attribute	Default	Description
`label`	(blank)	Visible label text. Also used as the accessible name when `icon-only` is set.
`value`	(blank)	Value emitted in `loomi-button-group-change`; falls back to the label or text content.
`icon`	(blank)	Built-in icon name from `@loomidev/icons`.
`icon-right`	`false`	Place the icon after the label. (boolean)
`icon-only`	`false`	Hide this item’s label visually and render a square icon button. (boolean)
`aria-label`	(blank)	Accessible label for icon-only items when `label` is not enough.
`selected`	`false`	Mark this item as active. (boolean)
`disabled`	`false`	Disable only this item. (boolean)

Slots

Slot	Description
(default)	Content placed inside the component.

Events

Event	Detail
`loomi-bg-click`	`{ value }` from the activated group item
`loomi-button-group-change`	`{ value, label, index }` when the selected item changes

Dependencies

@loomidev/core
@loomidev/icons
@loomidev/theme