Checkbox Specification - IgniteUI/igniteui-webcomponents GitHub Wiki
Checkbox Specification
Contents
Owned by
Team Name: Design and Web Development (DnD)
Developer: Silvia Ivanova
Designer: Stefan Ivanov
Requires approval from
- Simeon Simeonov | Date:
- Stefan Ivanov | Date: 21 Jul 21
Signed off by
- Product Owner: Radoslav Mirchev | Date:
- Radoslav Karaivanov | Date: July 23, 2021
Revision History
| Version | Users | Date | Notes |
|---|---|---|---|
| 1 | Silvia Ivanova | Date 20 July 2021 | Update specification |
1. Overview
The <igc-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. The <igc-checkbox> should also provide ways to set and get its validity when used in the context of Forms.
Acceptance criteria
- The checkbox component should have a toggle visual representation.
- 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 marked as 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
<igc-checkbox value="indeterminate checkbox" indeterminate disabled label-position="before">
Indeterminate checkbox
</igc-checkbox>
3.3. API
Properties
You should be able to configure the igc-checkbox by setting its properties:
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
name |
Sets the name of the checkbox | string | - | false |
value |
Sets the value of the checkbox | string | - | false |
checked |
Sets the initial state of the checkbox to checked |
boolean | false | true |
indeterminate |
Sets the initial state of the checkbox to indeterminate |
boolean | false | true |
disabled |
Sets the accessibility state of the checkbox | boolean | false | true |
required |
Makes the checkbox a required field | boolean | false | true |
invalid |
Sets the validity of the checkbox | boolean | false | true |
labelPosition |
Sets the label postion of the checkbox | Before / After | after | true |
ariaLabel |
Sets the aria-label of the native input. | string | - | false |
ariaLabelledby |
Sets the aria-labelledby of the native input. | string | - | false |
Events
The igc-checkbox should emit the following events:
| Name | Description | Type |
|---|---|---|
igcChange |
Emitted when the checkbox changes its checked state | - |
igcFocus |
Emitted when the checkbox gains focus | - |
igcBlur |
Emitted when the checkbox loses focus | - |
Methods
The igc-checkbox exposes the following methods:
| Name | Description | Arguments |
|---|---|---|
click |
Simulates a click on the checkbox. | - |
focus |
Sets focus on the checkbox. | options: FocusOptions |
blur |
Removes focus from the checkbox. | - |
reportValidity |
Checks for validity and shows the browser's validation message if the control is invalid. | - |
setCustomValidity |
Sets a custom validation message. If message is not empty, the field will be considered invalid. |
message: string |
Slots
| Name | Description |
|---|---|
| (default) | The checkbox label. |
CSS Parts
| Name | Description |
|---|---|
| base | The base wrapper of the checkbox. |
| control | The checkbox control. |
| label | The checkbox label. |
| indicator | The checkbox icon. |
4. Test Scenarios
Automation
- Scenario 1: Should set the checkbox checked state correctly.
- Scenario 2: Should set the checkbox disabled state correctly.
- Scenario 3: Should set the checkbox required option correctly.
- Scenario 4: Should change the checkbox indicator correctly.
- Scenario 5: Should position the checkbox label correctly.
- Scenario 6: Should set the checkbox validity correctly.
- Scenario 7: Should emit event when the checkbox checked state changes.
- Scenario 8: Should emit events when the checkbox gains or loses focus.