Button Group

The Button Group component provides a way to group related buttons together, creating a unified control that can operate in different selection modes. It’s useful for creating toggle buttons, radio-button-like interfaces, or multi-select button groups.

Usage

See the Example by Serhii Pimenov on CodePen.

Basic Button Group

<!-- Basic button group with default settings -->
<div data-role="button-group">
    <button>Option 1</button>
    <button>Option 2</button>
    <button>Option 3</button>
</div>

Single Selection Mode (Default)

<!-- Only one button can be active at a time (radio button behavior) -->
<div data-role="button-group" data-mode="one">
    <button>Option 1</button>
    <button class="active">Option 2</button>
    <button>Option 3</button>
</div>

Multiple Selection Mode

<!-- Multiple buttons can be active (checkbox behavior) -->
<div data-role="button-group" data-mode="multi">
    <button>Option 1</button>
    <button class="active">Option 2</button>
    <button class="active">Option 3</button>
</div>

Required Button Selection

<!-- At least one button must be selected -->
<div data-role="button-group" data-required-button="true">
    <button class="active">Option 1</button>
    <button>Option 2</button>
    <button>Option 3</button>
</div>

Custom Target Elements

<!-- Using elements other than buttons -->
<div data-role="button-group" data-targets=".option">
    <span class="option">Option 1</span>
    <span class="option active">Option 2</span>
    <span class="option">Option 3</span>
</div>

Custom Active Class

<!-- Using a custom class for active buttons -->
<div data-role="button-group" data-cls-active="highlighted">
    <button>Option 1</button>
    <button class="active">Option 2</button>
    <button>Option 3</button>
</div>

Plugin Parameters

The Button Group component can be configured with the following options:

Parameter	Type	Default	Description
buttongroupDeferred	number	0	Delay in milliseconds before initialization
targets	string	”button”	Selector for elements that should behave as buttons in the group
clsActive	string	""	Additional CSS class to apply to active buttons
requiredButton	boolean	false	Whether at least one button must be active
mode	string	Metro.groupMode.ONE	Selection mode: ONE (single selection) or MULTI (multiple selection)
onButtonClick	function	Metro.noop	Event handler triggered when a button is clicked
onButtonGroupCreate	function	Metro.noop	Event handler triggered when the button group is created

Global Configuration

You can set global defaults for all Button Group components:

Metro.buttonGroupSetup({
    clsActive: "highlighted",
    mode: Metro.groupMode.MULTI
});

API Methods

• destroy() - Removes the component and its event handlers.

const buttonGroup = Metro.getPlugin('#myButtonGroup', 'button-group');
buttonGroup.destroy();

Events

Event	Description
onButtonClick	Triggered when a button in the group is clicked
onButtonGroupCreate	Triggered when the button group is created

Example with Events

<div data-role="button-group"
     data-on-button-click="onButtonClicked"
     data-on-button-group-create="onGroupCreated">
    <button>Option 1</button>
    <button>Option 2</button>
    <button>Option 3</button>
</div>

<script>
function onButtonClicked(event) {
    console.log("Button clicked:", event.button);
}

function onGroupCreated(event) {
    console.log("Button group created:", event.element);
}
</script>

Styling with CSS Variables

The Button Group component can be styled using the following CSS variables:

Variable	Default (Light)	Dark Mode	Description
—button-group-active-background	#989898	#4b4b4b	Background color of active buttons
—button-group-active-color	#fff	#fff	Text color of active buttons

Example of Custom Styling

/* Custom styling for a specific button group */
#myCustomButtonGroup {
    --button-group-active-background: #2196F3;
    --button-group-active-color: #FFFFFF;
}

Available CSS Classes

Base Classes

• .button-group - The main container class for the button group

State Classes

• .active - Applied to active buttons within the group
• .js-active - Applied to buttons activated via JavaScript

Accessibility

For better accessibility:

1. Use semantic button elements when possible
2. Ensure there is sufficient color contrast between active and inactive states
3. Consider adding ARIA attributes to clarify the role and state of the button group

Best Practices

1. Use button groups for related options where users need to make a selection
2. Clearly indicate the active state with visual cues
3. For single-selection mode, consider making one option selected by default
4. Keep the number of options in a button group reasonable (typically 2-5)
5. Use consistent styling for button groups throughout your application