Overview of IntegralUI CheckBox for Angular

Created: 18 Nov 2019

IntegralUI CheckBox is a native Angular component that represents a check box. It replaces the standard HTML input element that acts as a check box. In this article, you will find general information about the check box component, including its properties, events and methods that you can use.

The demo shows five check boxes. First two check boxes have three-state values: checked, indeterminate and unchecked. The other three check boxes are only checked or unchecked. As you can see each check box can have custom appearance, a different image is used for each state of the check box.

How to Use IntegralUI CheckBox in Angular

To use the CheckBox component you need to do the following:

• In app template place the check box component using the iui-checkbox tag name
• Set values for different properties available
• Handle the events in your code

• HTML

<iui-checkbox [allowAnimation]="true" [threeState]="true" [(ngModel)]="checkValue" (checkStateChanged)="onCheckStateChanged($event)">CheckBox 1</iui-checkbox>
                            

By default, check box component has two values: checked or unchecked. To have three-state values, set the threeState property to true.

This component is compatible with Angular Forms, and you can apply the ngModel directive to it for its value. In this way, any change in the form data is applied to the check box and vice versa.

CheckBox as Editor in Other Angular Components

CheckBox component is also usable as an editor in other components. For example, you can add a check box to the cells in the Grid or TreeGrid component or inside items in ListBox, ListView and TreeView components. Simply, place the check box in the cell or item template, and when the control updates it will show a check box inside the specified cell or item.

Here is an example of check box inside the item template of the TreeView component:

• HTML

<iui-treeview [items]="data" [controlStyle]="treeStyle" #treeview>
    <ng-template let-item>
        <iui-checkbox [(ngModel)]="item.checked" (checkedChanged)="onItemCheckedChanged($event, item)"></iui-checkbox>
        <span [ngClass]="getItemIcon(item)"></span>
        <span class="trw-cbox-item-label">{{item.text}}</span>
    </ng-template>
</iui-treeview>
                            

You can also use the check box component in Angular Forms.

Available Properties, Events and Methods in IntegralUI CheckBox

Supported Properties

You can use the following properties to change the appearance and behavior of the CheckBox component:

• allowAnimation - determines whether changes to the check box are animated or not
• checked - specifies whether CheckBox is checked or not: true or false
• checkState - specifies one of the three state values: unchecked, indeterminate or checked
• controlStyle - specifies an object that contains all style settings for the component
• data - specifies an object that holds data related to the component
• enabled - determines whether the component is enabled or disabled
• name - uniquely identifies the component
• size - specifies the component width and height
• state - specifies the component state: disabled, hovered, etc.
• threeState - determines whether the CheckBox uses three or two state values
• value - holds the current progress value

Using the above properties, you can customize the CheckBox component in a way best suited for your application.

Supported Events

Here is a list of available events:

• checkedChanged - occurs when checked property value changes
• checkStateChanged - occurs when checkState property value changes
• enabledChanged - occurs when component is enabled or disabled
• stateChanged - occurs when component state changed: disabled, normal, hovered, selected
• valueChanged - occurs when component value changes

Depending on whether check box has two or three-state values, the checkedChanged or checkStateChanged event is fired. The event data contains two fields: checked and checkState. So whenever the checkState property value changes, a correct value is also applied to the checked property, and vice versa.

• Angular
• HTML

import { IntegralUICheckState } from './integralui/components/integralui.core';

. . .

public checkValue: IntegralUICheckState = IntegralUICheckState.Checked;

onCheckStateChanged(e: any){
    console.log("Checked value is: " + e.checked, and CheckState value is: ' + e.checkState);
}
                            

<iui-checkbox [allowAnimation]="true" [threeState]="true" [(ngModel)]="checkValue" (checkStateChanged)="onCheckStateChanged($event)">CheckBox 1</iui-checkbox>
                            

You can handle these events in your code, if you need to add a specific action once the check box value changes.

Note In three-state values, the check box accepts a value from IntegralUICheckState enumeration. It can be one of the following: Checked, Indeterminate or Unchecked.

Supported Methods

The following public methods are available:

• updateLayout - updates the component layout

How to Customize the Check Box Appearance

As in most IntegralUI components, the CheckBox has a set of CSS classes that govern its appearance. In addition, the appearance is determined by currently selected theme from available theme list.

To modify the check box appearance, you can use the controlStyle property where you can provide names for your CSS classes that will override specific component part depending on its state. The controlStyle property accepts an object with following settings:

chechBoxStyle = {
    general: {
        disabled: 'iui-checkbox-disabled',
        focused: 'iui-checkbox-focused',
        normal: 'iui-checkbox',
        hovered: 'iui-checkbox-hovered',
        selected: 'iui-checkbox-selected'
    },
    button: {
        general: 'iui-checkbox-btn',
        disabled: 'iui-checkbox-btn-disabled',
        checked: 'iui-checkbox-btn-checked',
        indeterminate: 'iui-checkbox-btn-indeterminate',
        unchecked: 'iui-checkbox-btn-unchecked'
    },
    content: {
        disabled: 'iui-checkbox-content-disabled',
        focused: 'iui-checkbox-content-focused',
        normal: 'iui-checkbox-content',
        hovered: 'iui-checkbox-content-hovered',
        selected: 'iui-checkbox-content-selected'
    }
}
                    

You only need to provide CSS classes for the component parts that you want to change. In this example, only the button part of the check box is changed. A new class that applies a custom image is used for each state:

• Angular
• HTML
• CSS

public ctrlStyle2: any = {
    button: { 
        checked: 'chb2-ovw-btn-checked',
        indeterminate: 'chb2-ovw-btn-indeterminate',
        unchecked: 'chb2-ovw-btn-unchecked'
    }
}
                            

<iui-checkbox [allowAnimation]="true" [controlStyle]="ctrlStyle2" [threeState]="true" [(ngModel)]="checkValue2">CheckBox 1</iui-checkbox>
                            

/* CheckBox 2 */
.chb2-ovw-btn-checked span
{
    background-image: url(src/app/resources/checkbox/checkbox-checked.png);
}
.chb2-ovw-btn-indeterminate span
{
    background-image: url(src/app/resources/checkbox/checkbox-indeterminate.png);
}
.chb2-ovw-btn-unchecked span
{
    background-image: url(src/app/resources/checkbox/checkbox-unchecked.png);
}
                            

By setting the allowAnimation property to false, you can disable animations of the check box state.

Conclusion

IntegralUI CheckBox component for Angular replaces the standard check box element. Using different properties and events and by providing your own CSS classes, you can customize the check box appearance and behavior. You can use your own images to override the appearance of the check mark for each state. CheckBox component can have two or three-state values, that are true/false or checked/indeterminate/unchecked value. The check box is also compatible with Angular Forms and can be used as part of it.

The CheckBox component is part of IntegralUI Web.