Button Group

Overview

A button group is a touch-friendly approach for selecting exactly one option from a short list of options.

Implementation approaches for selecting one item from a list

If your use case is prompting the user to select exactly one item from a list, the best implementation approach to use is based on the number of list items the user can select from:

• If the number of list items is small (say 5 items or less) and the list items can all be displayed horizontally in a row, then display them as a button group.
  • This is the use case covered in this document.
• If the number of list items is relatively small and all list items need to remain visible on the screen at once, then display them as a vertical list of radio buttons.
• If the number of list items is medium (say larger than 5 but smaller than around 50 items), then display the list in a dropdown input that contains all possible values.
• If the number of list items is large (say larger than 50 items but smaller than around 1000 items), then use a regular text input with autocomplete functionality, where all list items that are a subset of the current input display in a dropdown. Since the user’s input is freeform, you’ll still need to validate it.
• If the number of list items is very large (say larger than 1000 items), then just prompt for freeform text and validate that.

Development

Web component development

Component reference

rui-button-group

rui-button-group-option

Implementation

Begin by importing the rui-buttons module into your application.

// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-buttons/rui-buttons-imports';

Define a backing value in the controller that will contain the selected value for the button group. Initialize that property to one of the value options in the button group.

public flavorValue: string = 'Cho';

Add an instance of rui-button-group to your markup. Nest one or more rui-button-group-option components within the button group. Bind value to the TypeScript property that stores the backing value for this button group. Update that backing property when the rui-button-group-value-change event fires.

<rui-button-group [value]="flavorValue" (rui-button-group-value-change)="flavorValue = $event.detail">
    <rui-button-group-option value="Cho">Chocolate</rui-button-group-option>
    <rui-button-group-option value="Van">Vanilla</rui-button-group-option>
    <rui-button-group-option value="Str">Strawberry</rui-button-group-option>
</rui-button-group>

Using Templates in Button Groups

There may be scenarios where you need to display multiple data in button group options instead of just displaying a simple text value. It turns out this is straightforward since the button group option content is projected and not just a simple string property. Let’s take a look at an example illustrating this.

First, let’s create a new class to define the object that will hold the data.

export class ShippingMethod {
    constructor(
        public value: string,
        public name: string,
        public price: string
    ) { }
}

Import the newly created class into your TypeScript file. Define an array of shipping methods and an array of shipping method button options.

import { ShippingMethod } from '../classes/shipping-method';

export class ButtonGroupComponent implements OnInit {

    public shippingMethodList: ShippingMethod[] = [];

    ngOnInit() {
        // Create list of shipping methods
        this.shippingMethodList = new Array<ShippingMethod>();
        this.shippingMethodList.push(new ShippingMethod('USPS', 'US Postal Service', '4.95'));
        this.shippingMethodList.push(new ShippingMethod('UPS Ground', 'UPS Ground', '6.95'));
        this.shippingMethodList.push(new ShippingMethod('UPS Overnight', 'UPS Overnight', '18.90'));

        // Auto-select the first item in the list
        this.shippingMethod.setValue(this.shippingMethodList[0].value);
    }
}

We now add the rui-button-group element to the markup. This is a vertical button group in our example, so we bind isVertical to true. We nest the template within each button group option.

<rui-button-group value="{{shippingMethod.value}}" (rui-button-group-value-change)="updateShippingMethod($event)" [isVertical]="true">

    <rui-button-group-option *ngFor="let shippingMethod of shippingMethodList" value="{{shippingMethod.value}}">
        <div class="shipping-option-button">
            <span class="shipping-option-name">{{shippingMethod.name}}</span>
            <span class="shipping-option-price">&dollar;{{shippingMethod.price}}</span>
        </div>
    </rui-button-group-option>

</rui-button-group>

Selecting Multiple Options in a Button Group

Button groups support either a single selection or multiple selection.

For multiple selection, as we saw in the other examples, first define an array property in the TypeScript that will contain the selected values for the button group. Initialize that property to the value of one or more of the options in the button group.

public selectedToppings = [ 'Pepperoni', 'BlackOlives' ];

Then add an instance of rui-button-group to your markup with a separate rui-button-group-option for each of the button group options. Bind valueArray to the TypeScript array property that stores the backing value for this button group. Handle the rui-button-group-value-change event, storing the event’s detail back into the backing value in the TypeScript. Bind isMultiple to true to allow the component to accept multiple options.

<rui-button-group [isMultiple]="true" [valueArray]="selectedToppings" (rui-button-group-value-change)="selectedToppings = $event.detail">
    <rui-button-group-option value="Pepperoni">Pepperoni</rui-button-group-option>
    <rui-button-group-option value="Mushroom">Mushroom</rui-button-group-option>
    <rui-button-group-option value="ExtraCheese">Extra cheese</rui-button-group-option>
    <rui-button-group-option value="Sausage">Sausage</rui-button-group-option>
    <rui-button-group-option value="Onion">Onion</rui-button-group-option>
    <rui-button-group-option value="BlackOlives">Black olives</rui-button-group-option>
    <rui-button-group-option value="GreenPepper">Green pepper</rui-button-group-option>
</rui-button-group>

Angular wrapper development

Wrapper reference

jha-button-group

jha-button-group-option

Implementation

Begin by importing the JhaButtonsModule module into your application.

// import into app.module
import { JhaButtonsModule } from '@jkhy/responsive-ui-angular/jha-buttons';

@NgModule({
    imports: [
        ...
        JhaButtonsModule,
        ...
    ]
})
export class AppModule(){}

Button Group in a Reactive Form

Define the options for the button group using an array of JhaButtonGroupOption objects in your TypeScript.

import { JhaButtonGroupOption } from '@jkhy/responsive-ui-angular/jha-buttons';

public addressTypeOptions: JhaButtonGroupOption[] = [
    new JhaButtonGroupOption('Domestic', 'Domestic'),
    new JhaButtonGroupOption('International', 'International')
];

Then add an instance of jha-button-group to your markup. Specify the formControlName for this field in the Reactive form. Bind jhaOptions to the array of JhaButtonGroupOption objects defined in the TypeScript.

<jha-button-group formControlName="addressType" [jhaOptions]="addressTypeOptions"></jha-button-group>

Button Group Not in a Reactive Form

Define a property in the TypeScript that will contain the selected value for the button group. Initialize that property to one of the options in the button group.

public flavorValue: string = 'Cho';

Define the options for the button group using an array of JhaButtonGroupOption objects in your TypeScript.

import { JhaButtonGroupOption } from '@jkhy/responsive-ui-angular/jha-buttons';

public flavorOptions: JhaButtonGroupOption[] = [
    new JhaButtonGroupOption('Chocolate', 'Cho'),
    new JhaButtonGroupOption('Vanilla', 'Van'),
    new JhaButtonGroupOption('Strawberry', 'Str')
];

Then add an instance of jha-button-group to your markup. Two-way bind jhaValue to the TypeScript property that stores the backing value for this button group. Bind jhaOptions to the array of JhaButtonGroupOption objects defined in the TypeScript.

<jha-button-group [(jhaValue)]="flavorValue" [jhaOptions]="flavorOptions"></jha-button-group>

Using Templates in Button Groups

There may be scenarios where you need to display multiple data in button group options instead of just displaying a simple text value. This can be done using ng-template.

First, let’s create a new class to define the object that will hold the data.

export class ShippingMethod {
    constructor(
        public value: string,
        public name: string,
        public price: string
    ) { }
}

Import the newly created class and the JhaButtonGroupOption class into your TypeScript file. Define an array of shipping methods and an array of shipping method button options.

Build the array of shipping methods, then loop through that array to build a list of button options.

import { ShippingMethod } from '../classes/shipping-method';
import { JhaButtonGroupOption } from '@jkhy/responsive-ui-angular/jha-buttons';

export class ButtonGroupComponent implements OnInit {

    public shippingMethodList: ShippingMethod[] = [];
    public shippingMethodOptions: JhaButtonGroupOption[] = [];

    ngOnInit() {
        this.shippingMethodList = new Array<ShippingMethod>();
        this.shippingMethodList.push(new ShippingMethod('USPS', 'US Postal Service', '4.95'));
        this.shippingMethodList.push(new ShippingMethod('UPS Ground', 'UPS Ground', '6.95'));
        this.shippingMethodList.push(new ShippingMethod('UPS Overnight', 'UPS Overnight', '18.90'));

        // Add these to the list of shipping options
        for (let i = 0; i < this.shippingMethodList.length; i++ ) {
            this.shippingMethodOptions.push(new JhaButtonGroupOption(this.shippingMethodList[i].name, this.shippingMethodList[i]));
        }
    }
}

Add the jha-button-group element to your markup. Set the formControlName and bind jhaOptions to the array of shippingMethodOptions. In our example, this is a vertical button group, so jhaIsVertical is bound to true.

Create an ng-template and build the markup to match your interface.

<jha-button-group formControlName="shippingMethod" [jhaOptions]="shippingMethodOptions" [jhaIsVertical]="true">
    <ng-template let-shippingOption>
        <div class="shipping-option-button">
            <span class="shipping-option-name">{{shippingOption.name}}</span>
            <span class="shipping-option-price">${{shippingOption.value.price}}</span>
        </div>
    </ng-template>
</jha-button-group>

Selecting Multiple Options in a Button Group

Button groups, whether inside of a reactive form or not, can be set to accept multiple options.

As in the other examples, define a property in the TypeScript that will contain the selected values for the button group. Initialize that property to the value of one or more of the options in the button group.

public flavorValues: string[] = ['Cho'];

Define the options for the button group using an array of JhaButtonGroupOption objects in your TypeScript.

import { JhaButtonGroupOption } from '@jkhy/responsive-ui-angular/jha-buttons';

public flavorOptions: JhaButtonGroupOption[] = [
    new JhaButtonGroupOption('Chocolate', 'Cho'),
    new JhaButtonGroupOption('Vanilla', 'Van'),
    new JhaButtonGroupOption('Strawberry', 'Str')
];

Then add an instance of jha-button-group to your markup. Two-way bind jhaValue to the TypeScript property that stores the backing value for this button group. Bind jhaOptions to the array of JhaButtonGroupOption objects defined in the TypeScript. Finally, bind jhaIsMultiple to true to allow the component to accept multiple options.

<jha-button-group [(jhaValue)]="flavorValues" [jhaOptions]="flavorOptions" [jhaIsMultiple]="true"></jha-button-group>

Component playground

Design

Figma design

Change the button text to an appropriate value. Resize the button to fit the text, but be careful that you’re resizing the outer component and not an inner layer within the component.

Adobe XD design

Change the button text to an appropriate value. Resize the button to fit the text, but be careful that you’re resizing the outer component and not an inner layer within the component.