Light Dark System

Button Group

<zn-button-group> | ZnButtonGroup
Since 1.0 experimental

Short summary of the component’s intended use.

First Inner 1 Inner 2 Last 
<zn-button-group>
  <zn-button>First</zn-button>
  <zn-button>Inner 1</zn-button>
  <zn-button>Inner 2</zn-button>
  <zn-button>Last</zn-button>
</zn-button-group>

Examples

Basic Usage

By default, button groups display buttons horizontally with no gaps, creating a seamless connected appearance.

Left Center Right 
<zn-button-group>
  <zn-button>Left</zn-button>
  <zn-button>Center</zn-button>
  <zn-button>Right</zn-button>
</zn-button-group>

Direction

Use the direction attribute to control the orientation of the button group. The default is horizontal, but you can set it to vertical for a stacked layout.

Horizontal 1 Horizontal 2 Horizontal 3

Vertical 1 Vertical 2 Vertical 3 
<zn-button-group direction="horizontal">
  <zn-button>Horizontal 1</zn-button>
  <zn-button>Horizontal 2</zn-button>
  <zn-button>Horizontal 3</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group direction="vertical">
  <zn-button>Vertical 1</zn-button>
  <zn-button>Vertical 2</zn-button>
  <zn-button>Vertical 3</zn-button>
</zn-button-group>

Grow

Use the grow attribute to make buttons expand equally to fill the full width of their container. This is useful for creating full-width button groups.

First Second Third Fourth 
<zn-button-group grow>
  <zn-button>First</zn-button>
  <zn-button>Second</zn-button>
  <zn-button>Third</zn-button>
  <zn-button>Fourth</zn-button>
</zn-button-group>

Alignment

By default, button groups are right-aligned (flex-end). Use the start attribute to align buttons to the left (flex-start).

Right Aligned 1 Right Aligned 2 Right Aligned 3

Left Aligned 1 Left Aligned 2 Left Aligned 3 
<zn-button-group>
  <zn-button>Right Aligned 1</zn-button>
  <zn-button>Right Aligned 2</zn-button>
  <zn-button>Right Aligned 3</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group start>
  <zn-button>Left Aligned 1</zn-button>
  <zn-button>Left Aligned 2</zn-button>
  <zn-button>Left Aligned 3</zn-button>
</zn-button-group>

Spacing

Use the gap attribute to add spacing between buttons. This creates visual separation while maintaining the logical grouping.

First Second Third Fourth 
<zn-button-group gap>
  <zn-button>First</zn-button>
  <zn-button>Second</zn-button>
  <zn-button>Third</zn-button>
  <zn-button>Fourth</zn-button>
</zn-button-group>

Gap with Grow

Combine gap and grow attributes to create evenly-spaced, full-width button groups.

First Second Third Fourth 
<zn-button-group gap grow>
  <zn-button>First</zn-button>
  <zn-button>Second</zn-button>
  <zn-button>Third</zn-button>
  <zn-button>Fourth</zn-button>
</zn-button-group>

Button Variants

Button groups work with all button variants including colors and styles.

Default Secondary Success

Error Warning Info

Outline 1 Outline 2 Outline 3 
<zn-button-group>
  <zn-button color="default">Default</zn-button>
  <zn-button color="secondary">Secondary</zn-button>
  <zn-button color="success">Success</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group gap>
  <zn-button color="error">Error</zn-button>
  <zn-button color="warning">Warning</zn-button>
  <zn-button color="info">Info</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group>
  <zn-button outline>Outline 1</zn-button>
  <zn-button outline>Outline 2</zn-button>
  <zn-button outline>Outline 3</zn-button>
</zn-button-group>

Panel Background

Use the panel-bg attribute to give every button in the group the icon button look: a panel background with a border, text-coloured labels and a tinted hover. Color variants tint the label and icon instead of filling the button.



List Grid Delete

Cancel Save 
<zn-button-group panel-bg>
  <zn-button icon="format_bold"></zn-button>
  <zn-button icon="format_italic"></zn-button>
  <zn-button icon="format_underlined"></zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group panel-bg>
  <zn-button icon="view_list">List</zn-button>
  <zn-button icon="grid_view">Grid</zn-button>
  <zn-button icon="delete" color="error">Delete</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group panel-bg gap>
  <zn-button>Cancel</zn-button>
  <zn-button>Save</zn-button>
</zn-button-group>

Set aria-pressed="true" on the selected button to show it in its active colour, for segmented toggles.

Mine Everyone 
<zn-button-group panel-bg class="panel-bg-toggle">
  <zn-button aria-pressed="false">Mine</zn-button>
  <zn-button aria-pressed="true">Everyone</zn-button>
</zn-button-group>

<script type="module">
  const group = document.querySelector('.panel-bg-toggle');
  group.addEventListener('click', event => {
    const clicked = event.target.closest('zn-button');
    if (!clicked) return;
    group.querySelectorAll('zn-button').forEach(button => {
      button.setAttribute('aria-pressed', String(button === clicked));
    });
  });
</script>

With Icons

Button groups work seamlessly with icon buttons.



Add Edit Delete 
<zn-button-group>
  <zn-button icon="format_bold"></zn-button>
  <zn-button icon="format_italic"></zn-button>
  <zn-button icon="format_underlined"></zn-button>
  <zn-button icon="format_align_left"></zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group gap>
  <zn-button icon="add" color="success">Add</zn-button>
  <zn-button icon="edit" color="info">Edit</zn-button>
  <zn-button icon="delete" color="error">Delete</zn-button>
</zn-button-group>

Vertical with Gap

Combine vertical direction with gap for a spaced vertical layout.

Option 1 Option 2 Option 3 Option 4 
<zn-button-group direction="vertical" gap>
  <zn-button>Option 1</zn-button>
  <zn-button>Option 2</zn-button>
  <zn-button>Option 3</zn-button>
  <zn-button>Option 4</zn-button>
</zn-button-group>

Action Button Groups

A common pattern is to use button groups for action buttons like save/cancel or submit/reset combinations.

Cancel Save Changes

Reset Submit 
<zn-button-group start>
  <zn-button color="transparent">Cancel</zn-button>
  <zn-button color="success">Save Changes</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group gap>
  <zn-button color="secondary">Reset</zn-button>
  <zn-button color="default">Submit</zn-button>
</zn-button-group>

Segmented Controls

Button groups can be used to create segmented control-like interfaces for toggling between views or options.

Day Week Month Year

List Grid Board 
<zn-button-group>
  <zn-button>Day</zn-button>
  <zn-button>Week</zn-button>
  <zn-button>Month</zn-button>
  <zn-button>Year</zn-button>
</zn-button-group>

<br />
<br />

<zn-button-group>
  <zn-button icon="view_list">List</zn-button>
  <zn-button icon="grid_view">Grid</zn-button>
  <zn-button icon="view_kanban">Board</zn-button>
</zn-button-group>

Toolbar Pattern

Button groups are ideal for creating toolbars with related actions.

<zn-button-group gap>
  <zn-button icon="undo" color="transparent"></zn-button>
  <zn-button icon="redo" color="transparent"></zn-button>
</zn-button-group>

<zn-button-group>
  <zn-button icon="format_bold"></zn-button>
  <zn-button icon="format_italic"></zn-button>
  <zn-button icon="format_underlined"></zn-button>
</zn-button-group>

<zn-button-group>
  <zn-button icon="format_align_left"></zn-button>
  <zn-button icon="format_align_center"></zn-button>
  <zn-button icon="format_align_right"></zn-button>
</zn-button-group>

Responsive Wrapping

Button groups support wrapping by default, allowing buttons to flow to multiple lines on smaller screens.

Button 1 Button 2 Button 3 Button 4 Button 5 Button 6 
<div style="max-width: 300px;">
  <zn-button-group>
    <zn-button>Button 1</zn-button>
    <zn-button>Button 2</zn-button>
    <zn-button>Button 3</zn-button>
    <zn-button>Button 4</zn-button>
    <zn-button>Button 5</zn-button>
    <zn-button>Button 6</zn-button>
  </zn-button-group>
</div>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.185/dist/components/button-group/button-group.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.185/dist/components/button-group/button-group.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/button-group/button-group.js';

Slots

Name Description
(default) The default slot.

Learn more about using slots.

Properties

Name Description Reflects Type Default
panelBackground
panel-bg 		Gives every button in the group the icon-button look: panel background, border, text-colored ink and a tab-tint hover. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
zn-event-name Emitted as an example. -

Learn more about events.

Custom Properties

Name Description Default
--grow Use flex-grow to fill available space.
--start Justify content at the start of the flex space.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <zn-example>