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>

Set circle (on the group or on a single item) to render a full-radius icon button - for icon-only buttons. It implies icon-only, and overrides the group’s radius.

1
<loomi-button-group circle color="primary" aria-label="Row actions">
2
  <loomi-button-group-item icon="pencil" value="edit" aria-label="Edit"></loomi-button-group-item>
3
  <loomi-button-group-item icon="trash" value="delete" aria-label="Delete"></loomi-button-group-item>
4
</loomi-button-group>
5

6
<!-- one circular item in an otherwise labeled group -->
7
<loomi-button-group aria-label="Views">
8
  <loomi-button-group-item label="Day" value="day" selected></loomi-button-group-item>
9
  <loomi-button-group-item label="Week" value="week"></loomi-button-group-item>
10
  <loomi-button-group-item circle icon="plus" value="add" aria-label="Add view"></loomi-button-group-item>
11
</loomi-button-group>

Tooltips

Set tooltip on an item for a built-in <loomi-tooltip> on hover and keyboard focus; tooltip-position picks the side (top by default, flipping when there’s no room). No wrapping needed, and selection, sizing and the segmented look are unchanged. Tooltip text that differs from the item’s name is also exposed as its accessible description.

1
<loomi-button-group icon-only aria-label="Views">
2
  <loomi-button-group-item icon="list-bullet" label="View as list" tooltip="View as list" selected></loomi-button-group-item>
3
  <loomi-button-group-item icon="map" label="View as map" tooltip="View as map"></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.
Whenever an item’s label is visually hidden (icon-only or circle on the group or the item), its inner button gets an aria-label from the item’s own aria-label, else its label, so it announces as e.g. “View as list, toggle button, pressed”. Give every icon-only item one or the other.

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`. See Sizing.
`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)
`circle`	`false`	Full-radius icon buttons for every item; implies `icon-only`, overrides `radius`. (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)
`circle`	`false`	Full-radius icon button for this item; implies `icon-only`, overrides the group’s `radius`. (boolean)
`aria-label`	(blank)	Accessible label for icon-only items when `label` is not enough.
`tooltip`	(blank)	Tooltip text shown on hover and keyboard focus.
`tooltip-position`	`top`	`top` \| `bottom` \| `left` \| `right`; flips when there isn’t room.
`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
@loomidev/tooltip