Checkbox

Components > Editing Data > Checkbox

Use this component to...

Prompt the user for one or more true/false values

See this component in action...

Test out this component in a hosted version of the sample app

Overview

Use the checkbox component to prompt the user for one or more Boolean (true/false) values.

In Responsive UI, we primarily use checkboxes for editing Boolean fields in a form, where the form is posted with a Save button. The user typically must take a separate action — i.e. pressing the Save button — for the checkbox state to take effect in the system.

Single Checkbox for a Form Field

When you have a single checkbox for a field in a form, place the field label in the left column and the checkbox input in the right column. This keeps all field labels on the left and all field value editors on the right, a standard previously established by the UI Committee. The checkbox displays without a label directly to the right of it since its field label is already displayed in the left column.

A field that displays a single checkbox, with the field label on the left and the checkbox on the right

Multiple Checkboxes for a Form Field

A field that allows the user to select multiple options may display multiple checkboxes in the field value column on the right. The field label displays in the left column, with the checkboxes displaying in the column on the right. In addition, each checkbox displays a separate label for that individual option to the right of the checkbox. ÇThis is the only time a checkbox displays a label to its immediate right in Responsive UI.

A field that displays multiple checkboxes, with the field label on the left, the checkboxes on the right, and a sub-label next to each checkbox

Development

Web component development

Component reference

rui-checkbox

Module: rui-input - Package: @jkhy/responsive-ui-wc

Allows the user to toggle a value on and off

Name	Type	Default	Description
value	string	null	Bind this property to a backing value in your controller to set the initial value for the checkbox.
rui-value-change	event		This event fires when the checkbox’s value changes. The new value and checked status is passed in the event detail. Reference $event.detail.value or $event.detail.checked. Use this event to update the backing value in your controller.
labelText	string	null	If the toggle needs to be labeled, specify its label text with this property.
isChecked	boolean	false	Bind this property to true to initially check the checkbox.
isDisabled	boolean	false	Specifies whether the toggle is disabled.
name	string	null	Specify the name of the input with this property.
inputId	string	null	To apply a specific id to the input, use this property. Otherwise an id will be automatically generated, linking it to the label.

Implementation

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

Import the module

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

Single Checkbox Example

The single checkbox approach is used to set a true/false value for an individual property.

Define a field for the value in the controller, then add a rui-checkbox instance for the field in the HTML. Bind the value property to the appropriate field in the form and set the rui-value-change event to toggle the value when clicked.

Example:

Checkbox HTML with boolean value

<rui-checkbox 
    inputId="field-account-is-active" 
    name="accountIsActive" 
    labelText="Account Active" 
    [value]="acctActiveVal" 
    (rui-value-change)="acctActiveVal = !acctActiveVal">
</rui-checkbox>

If the value is a string, set the rui-value-change to a backing function to handle update.

Checkbox HTML with string value

<rui-checkbox 
    inputId="field-account-is-active" 
    name="accountIsActive" 
    labelText="Account Active" 
    [value]="acctActiveVal" 
    (rui-value-change)="acctActiveValChange($event)">
</rui-checkbox>

Then check if checkbox is checked, and if so, update value.

String checkbox value update

public acctActiveValChange(e: any) {
    if (e.detail.checked) {
        this.ruiValue = e.detail.value;
    } else {
        this.ruiValue = '';
    }
}

Multiple Checkbox Example

The multiple checkbox approach is used to select one or more options from a list.

Set up an array to iterate over for your checkbox options.

Set up checkbox options

interface AccountType {
    label: string;
    value: string;
    inactive: boolean;
}

...

public accountTypeList: AccountType[] = [
    { label: 'Checking', value: 'Checking', inactive: false },
    { label: 'Business Checking', value: 'Business-Checking', inactive: false },
    { label: 'Student Checking', value: 'Student-Checking', inactive: false },
    { label: 'Savings', value: 'Savings', inactive: false },
    { label: 'Money Market', value: 'Money-Market', inactive: false },
    { label: 'CD', value: 'CD', inactive: true },
    { label: 'IRA', value: 'IRA', inactive: false }
];

Add a rui-checkbox, iterating through the array setting the labelText, value, isChecked and isDisabled statuses, and set the rui-value-change event to a backing function to handle the value change.

Checkbox HTML for multiple options

<rui-checkbox
    *ngFor="let accountType of accountTypeList"
    inputId="field-account-type-{{accountType.value}}" 
    name="accountTypes" 
    labelText="{{accountType.label}}" 
    [value]="accountType.value"
    [isDisabled]="accountType.inactive"
    (rui-value-change)="accountTypeValChange($event)"
    [isChecked]="accountTypeCheckVal(accountType.value)">
</rui-checkbox>

Back in the TypeScript, create the model value, and set up functions to handle rui-value-change and determine isChecked.

Update model and determine checked status

public selectedAcctTypes: string[] = ['Checking','Savings'];

public accountTypeValChange(e: any) {
    if (e.detail.checked) {
        this.selectedAcctTypes.push(e.detail.value);
    } else {
        const index = this.selectedAcctTypes.findIndex(x => x === e.detail.value);
        this.selectedAcctTypes.splice(index, 1);
    }
}

public accountTypeCheckVal(e: any) {
    if (this.selectedAcctTypes.includes(e)) {
        return true;
    } else {
        return false;
    }
}

Angular component development

Component reference

jha-checkbox

Module: jha-forms - Package: @jkhy/responsive-ui-angular

Allows the user to toggle a value on and off

Name	Type	Default	Description
jhaCheckboxVal	string	null	Bind this property to a backing value in your controller to set the initial value for the checkbox.
jhaCheckboxValChange	event		This event fires when the checkbox’s value changes. The new value is returned by the event. Use this event to update the backing value in your controller.
jhaLabel	string	null	If the toggle needs to be labeled, specify its label text with this property.
jhaIsChecked	boolean	false	Bind this property to true to initially check the checkbox.
jhaIsDisabled	boolean	false	Specifies whether the toggle is disabled.
jhaName	string	null	Specify the name of the input with this property.
jhaInputId	string	null	To apply a specific id to the input, use this property. Otherwise an id will be automatically generated, linking it to the label.

Implementation

Begin by importing the jha-input module into your application.

Import the module

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

@NgModule({
    imports: [
        ...
        JhaFormsModule.forRoot(),
        ...
    ]
})

export class AppModule(){}

Single Checkbox Example

The single checkbox approach is used to set a true/false value for an individual property.

Define a field for the value in the controller, then add a jha-checkbox instance for the field in the HTML. Bind the ngModel property to the checkbox value.

Example:

Checkbox HTML

<jha-checkbox
    jhaInputId="field-account-is-active" 
    jhaName="accountIsActive" 
    jhaLabel="Account Active" 
    [(ngModel)]="acctActiveVal">
</jha-checkbox>

If using FormBuilder, set a jhaCheckboxValue and bind the formControl attribute to a backing property.

Example:

FormBuilder Checkbox

<jha-checkbox
    jhaInputId="field-account-type" 
    jhaName="accountType" 
    jhaLabel="Account Type" 
    jhaCheckboxVal="Savings" 
    [formControl]="acctType">
</jha-checkbox>

Then set up the FormBuilder in your TypeScript:

FormBuilder Checkbox TypeScript

constructor(private formBuilder: FormBuilder) {
    this.form = this.formBuilder.group({
        acctType: ['', [Validators.required]]
    })
}

get acctType() { return this.form.get('acctType'); }

Multiple Checkbox Example

The multiple checkbox approach is used to select one or more options from a list.

Set up an array to iterate over for your checkbox options.

Set up checkbox options

interface AccountType {
    label: string;
    value: string;
    inactive: boolean;
}

...

public accountTypeList: AccountType[] = [
    { label: 'Checking', value: 'Checking', inactive: false },
    { label: 'Business Checking', value: 'Business-Checking', inactive: false },
    { label: 'Student Checking', value: 'Student-Checking', inactive: false },
    { label: 'Savings', value: 'Savings', inactive: false },
    { label: 'Money Market', value: 'Money-Market', inactive: false },
    { label: 'CD', value: 'CD', inactive: true },
    { label: 'IRA', value: 'IRA', inactive: false }
];

Add a jha-checkbox, iterating through the array setting the jhaLabel, jhaCheckboxVal, jhaIsChecked and jhaIsDisabled statuses, and set the jhaCheckboxValChange event to a backing function to handle the value change.

Checkbox HTML for multiple options

<jha-checkbox
    *ngFor="let accountType of accountTypeList"
    jhaInputId="field-account-type-{{accountType.value}}" 
    jhaName="accountTypes" 
    [jhaLabel]="accountType.label" 
    [jhaCheckboxVal]="accountType.value" 
    (jhaCheckboxValChange)="accountTypeValChange(accountType.value)"
    [jhaIsChecked]="accountTypeCheckVal(accountType.value)">
</jha-checkbox>

Back in the TypeScript, create the model value, and set up functions to handle jhaCheckboxValChange and determine jhaIsChecked.

Update model and determine checked status

public selectedAcctTypes: string[] = ['Checking','Savings'];

public accountTypeValChange(e: any) {
    const index = this.jhaNgValue.findIndex(x => x === e);

    if (this.selectedAcctTypes.indexOf(e) === -1) {
        this.selectedAcctTypes.push(e);
    } else {
        this.selectedAcctTypes.splice(index, 1);
    }
}

public accountTypeCheckVal(e: any) {
    if (this.selectedAcctTypes.includes(e)) {
        return true;
    } else {
        return false;
    }
}

If you’re using FormBuilder, send the $event and the element into the jhaCheckboxValChange bound method:

Checkbox HTML for multiple options

<jha-checkbox #jhaCheck
    *ngFor="let accountType of accountTypeList"
    jhaInputId="field-account-type-{{accountType.value}}" 
    jhaName="accountTypes" 
    [jhaLabel]="accountType.label" 
    [jhaCheckboxVal]="accountType.value" 
    (jhaCheckboxValChange)="accountTypeValChange(event, jhaCheck)"
    [jhaIsChecked]="accountTypeCheckVal(jhaCheck)">
</jha-checkbox>

Then use the function to update the FormArray value:

Update FormBuilder control with selection

public accountTypeValChange(e: any, el: any) {
    const selectedAcctTypes: FormArray = this.form.get('selectedAcctTypes') as FormArray;

    if (e) {
        selectedAcctTypes.push(new FormControl(e));
    } else {
        const index = selectedAcctTypes.controls.findIndex(x => x.value === el.origValue);
        selectedAcctTypes.removeAt(index);
    }
}

public accountTypeCheckVal(e: any) {
    const currentVal = this.form.get('selectedAcctTypes').value;

    if (currentVal.includes(e.jhaCheckboxVal)) {
        return true;
    } else {
        return false;
    }
}

Component playground

Design

Figma design

Figma design info

You can find this component in the Components - Forms page in the Figma UI Kit.

Dev Component	Design Component Name
Checkbox	RUI / Forms / Checkbox

Adobe XD design

Adobe XD design info

You can find this component in these artboards in the Adobe XD design samples:

Sample App - Editing Form Data

Dev Component	Design Component Name
Checkbox - checked	JHA / Forms / Checkbox / Checked
Checkbox - unchecked	JHA / Forms / Checkbox / Unchecked

Support options

Have questions on this topic?

Join the Responsive UI team in Microsoft Teams to connect with the community.

See something in this page that needs to change?

Send us feedback on this page.

Last updated Thu Oct 12 2023