Checkbox Specification

Owned by

Team Name: Phoenix

Developer: Zdravko Kolev

Designer: Stefan Ivanov

Requires approval from

Simeon Simeonov | Date:

Signed off by

Product Owner: Radoslav Mirchev | Date:
Radoslav Karaivanov | Date:

Revision History

Version	Users	Date	Notes
1	Zdravko Kolev	Date 2 Feb 2017	Initial spec
1.1	Konstantin Dinev	Date 18 Mar 2021	Adding missing properties
2	Stefan Ivanov	Date 21 Jul 2021	Update spec template

1. Overview

The <igx-checkbox> component is used to provide a capability for making a binary choice for a certain condition. It follows the native browser checkbox element and behaves in the same way.

Objectives

It is providing API for the most common use cases when it comes to making a binary choice for a certain condition. It follows the native browser checkbox element and behaves in the same way.

Acceptance criteria

The checkbox component should have a toggle visual representation.
The checkbox component should have a clickable box.
The checkbox component should be identifiable via a property, like name.
The checkbox component should represent a unit of information, like value.
The checkbox component should provide a way to be disabled.
The checkbox component should provide a way to be a required field.
The checkbox component should have an indeterminate state.
The checkbox component should have the ability to add a corresponding label (before or after).
The checkbox component should be interacted via mouse and/or keyboard.
The checkbox component should be accessible.
The checkbox component should emit an event when it gains focus.
The checkbox component should emit an event when it loses focus.
The checkbox component should emit an event when its checked status changes.
The checkbox component should be able to report validation errors in the context of web forms.

2. User Stories

Developer stories:

Story 1: As a developer, I want to be able to provide a way to display a binary choice - true or false.
Story 2: As a developer, I want to be able to name the checkbox, so that I can easily identify it when used with other selection controls of the same type.
Story 3: As a developer, I want to be able to set the value of the checkbox, so that I can associate a piece of information with it.
Story 4: As a developer, I want to be able to specify the default state of the checkbox - checked, unchecked, or indeterminate.
Story 5: As a developer, I want to be able to disable the checkbox, so that the user cannot change its state.
Story 6: As a developer, I want to be able to place content between the opening and closing brackets of the checkbox component, so that it can be used as a corresponding label.
Story 7: As a developer, I want to be able to position the label of the checkbox either before or after the control, so that it better suits the design.
Story 8: As a developer, I want to be able to programmatically click the checkbox, so that I can interact with it via means other than a computer mouse.
Story 9: As a developer, I want to be able to programmatically focus the checkbox, so that I can manually trigger the focus event.
Story 10: As a developer, I want to be able to programmatically blur the checkbox, so that I can manually trigger the blur event.
Story 11: As a developer, I want to be able to listen to blur, focus, and change events, so that I can better manage the state of the checkbox component.
Story 12: As a developer, I want to be able to check the validity of the checkbox, so that I can handle form errors and/or warnings.
Story 13: As a developer, I want to be able to set a custom validation message, so that the users can easily identify and fix form errors and/or warnings.
Story 14: As a developer, I want to be able to customize the appearance of the checkbox component, so that it better fits the design language of my application.

End-user stories:

Story 1: As an end-user, I want to be shown a visual representation of certain state changes.
Story 2: As an end-user, I want to be able to identify if a checkbox is disabled or not.
Story 3: As an end-user, I want to be able to identify if a checkbox is checked, unchecked, or indeterminate.
Story 4: As an end-user, I want to be able to identify the option I am selecting via label or some other visual aid.
Story 5: As an end-user, I want to be able to identify if my selection is valid.

3. Functionality

3.1. End-User Experience

The checkbox component represents a small square box that changes its appearance according to the checkbox state. When unchecked, the box has only an outline. Changing the checkbox state to checked or indeterminate, the box became filled and an icon appears inside - a tick mark for checked state and a dash for the indeterminate. The checkbox component comes with an optional corresponding label that can be position either before or after the selection control. The user can click on both the box and the label to change the state of the checkbox.

3.2. Developer Experience

<igx-checkbox [checked]="task.done" (change)="handler($event)">
    {{ task.label }}
</igx-checkbox>

3.3. API

Properties

You should be able to configure the igx-checkbox by setting its properties:

Name	Description	Type	Default value	Reflected
`name`	Sets the name of the checkbox	string	-
`value`	Sets the value of the checkbox	string	-
`checked`	Sets the initial state of the checkbox to `checked`	boolean	false
`indeterminate`	Sets the initial state of the checkbox to `indeterminate`	boolean	false
`disabled`	Sets the accessibility state of the checkbox	boolean	false
`required`	Makes the checkbox a required field	boolean	false	`true`
`invalid`	Sets the validity of the checkbox	boolean	false	`true`
`label-position`	Sets the label postion of the checkbox	Before / After	after	`true`