Checkbox

The Ignite UI for Angular Checkbox component is a selection control that allows users to make a binary choice for a certain condition. It behaves similarly to the native browser checkbox.

Demo

Usage

At its core, the checkbox component allows for a choice between selected/unselected state. The default styling is done according to the selection controls specification in the Material Design guidelines.

First you need to import the IgxCheckboxModule in the app.module.ts file:

// app.module.ts

...
import { IgxCheckboxModule } from 'igniteui-angular';

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

To make the checkbox in the demo, add the following code inside the component template:

<igx-checkbox [checked]="true">
    Simple checkbox
</igx-checkbox>

Checkbox properties

Let's enhance the code above by binding the checkbox properties to some data. Say, we have an array of task objects, each having two properties: description and done. You can bind the checkbox component checked property to the underlying task object done property. Analogically, you can bind the value property to description. Optionally, you can also bind the change event and add some custom logic in the provided event handler method.

// tasks.component.ts
...
public tasks = [
  { done: true, description: 'Research' },
  { done: true, description: 'Implement' },
  { done: false, description: 'Test' },
];

...
statusChanged()
{
    // event handler logic
}

Enhance the component template by adding a checkbox for each task and then setting the corresponding property bindings:

<!--tasks.component.html-->

<igx-checkbox *ngFor="let task of tasks" [checked]="task.done">
    {{ task.description }}
</igx-checkbox>

Add some styles:

//task.component.scss

:host {
    display: flex;
    flex-flow: column nowrap;
    padding: 16px;
}

igx-checkbox {
    margin-top: 16px;
}

The final result would be something like that:

Label Positioning

You can position the label using the checkbox's labelPosition property:

<igx-checkbox labelPosition="before"></igx-checkbox>

If the labelPosition is not set, the label will be positioned after the checkbox.

Indeterminate Checkbox

In addition to the checked and unchecked states, there is a third state a checkbox can be in: indeterminate. In this state the checkbox is neither checked, nor unchecked. This is set using the checkbox's indeterminate property:

<igx-checkbox [indeterminate]="true"></igx-checkbox>

We can create an app that has a list of tasks that need to be done and one master checkbox that's going to be checked only if all the tasks are completed. Let's update the previous sample. Starting with the template:

<!-- app.component.html -->

<igx-checkbox 
    [readonly]="true" 
    [(ngModel)]="masterCheckbox.checked" 
    [(indeterminate)]="masterCheckbox.indeterminate" 
    (click)="toggleAll()"
>
All done
</igx-checkbox>
<igx-checkbox class="tasks" *ngFor="let task of tasks" [(ngModel)]="task.done">
    {{ task.description }}
</igx-checkbox>

Next, we're going to indent the subtasks, so it's more visual that they are part of the same group.

// app.component.scss

:host {
    display: flex;
    flex-flow: column nowrap;
    padding: 16px;
}

igx-checkbox {
    margin-top: 16px;
}

igx-checkbox.tasks {
    padding-left: 10px;
}

And finally, we'll create the logic of our application:

// app.component.ts

public tasks = [
    { done: true, description: "Research" },
    { done: true, description: "Implement" },
    { done: false, description: "Test" }
];

public get masterCheckbox() {
    return this.tasks.reduce(
        (acc, curr, idx, arr) => {
            acc.checked = acc.checked && curr.done;
            acc.done = curr.done ? acc.done + 1 : acc.done;
            acc.indeterminate = acc.done === arr.length ? false : !!acc.done;

            return acc;
        },
        {
            checked: true,
            done: 0,
            indeterminate: false
        }
    );
}

public toggleAll() {
    if (this.masterCheckbox.checked) {
        for (const task of this.tasks) {
            task.done = false;
        }
    } else {
        for (const task of this.tasks) {
            task.done = true;
        }
    }
}

After all that is done, our application should look like this:

Styling

To get started with styling the checkbox, we need to import the index file, where all the theme functions and component mixins live:

@import '~igniteui-angular/lib/core/styles/themes/index';

Then, we create a new theme that extends the igx-checkbox-theme and use some of its parameters to style the checkbox's items:

// in styles.scss
$custom-checkbox-theme: igx-checkbox-theme(
    $border-radius: 10px,
    $label-color: #011627,
    $empty-color: #ECAA53,
    $fill-color: #ECAA53,
    $tick-color: #011627,
);

Including Themes

The last step is to include the component theme in our application.

If $legacy-support is set to true, include the component theme like that:

 @include igx-checkbox($custom-checkbox-theme);
Note

If the component is using an Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep

:host {
     ::ng-deep {
        @include igx-checkbox($custom-checkbox-theme);
    }
}

If $legacy-support is set to false(default), include the component css variables like that:

@include igx-css-vars($custom-checkbox-theme);
Note

If the component is using an Emulated ViewEncapsulation, you still have to use :host because you need a global selector in order to override the variables.

:host {
    @include igx-css-vars($custom-checkbox-theme);
}

Demo

API References

Additional Resources

Our community is active and always welcoming to new ideas.