Switch Specification - IgniteUI/igniteui-webcomponents GitHub Wiki
Team Name: Design and Web Development (DnD)
Developer: Silvia Ivanova
Designer: Stefan Ivanov
- Simeon Simeonov | Date:
- Stefan Ivanov | Date: 20 Jul 2021
- Product Owner: Radoslav Mirchev | Date:
- Radoslav Karaivanov | Date: July 23, 2021
| Version | Users | Date | Notes |
|---|---|---|---|
| 1 | Silvia Ivanova | Date 16 July 2021 | Update specification |
The <igc-switch> component is used to provide a capability for making a binary choice of a single settings option.
It is providing API for the most common use cases when it comes to a binary choice for a certain condition. The <igc-switch> component should also provide ways to set and get its validity when used in the context of Forms.
- The switch component should have a toggle visual representation.
- The switch component should be identifiable via a property, like name.
- The switch component should represent a unit of information, like value.
- The switch component should provide a way to be disabled.
- The switch component should provide a way to be a required field.
- The switch component should have the ability to add a corresponding label (before or after).
- The switch component should be interacted via mouse and/or keyboard.
- The switch component should be accessible.
- The switch component should emit an event when it gains focus.
- The switch component should emit an event when it loses focus.
- The switch component should emit an event when its checked status changes.
- The switch component should be able to report validation errors in the context of web forms.
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 switch, 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 switch, 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 switch - checked or unchecked.
- Story 5: As a developer, I want to be able to disable the switch, 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 switch 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 switch 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 switch, 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 switch, so that I can manually trigger the focus event.
- Story 10: As a developer, I want to be able to programmatically blur the switch, 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 switch component.
- Story 12: As a developer, I want to be able to check the validity of the switch, 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 switch 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 switch is disabled or not.
- Story 3: As an end-user, I want to be able to identify if a switch is checked or not.
- 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.1. End-User Experience
The switch component displays a toggle changing the state of a single settings option. When selected, the switch thumb (a small circle) moves from left to right and changes the color of the component. It comes with an optional corresponding label that can be position either before or after the selection control. The user can click on both the circle and the label to change the state of the switch.
3.2. Developer Experience
<igc-switch value="checked switch" checked disabled label-position="before">
Checked Switch
</igc-switch>3.3. API
You should be able to configure the igc-switch by setting its properties:
| Name | Description | Type | Default value | Reflected |
|---|---|---|---|---|
name |
Sets the name of the switch | string | - | false |
value |
Sets the value of the switch | string | - | false |
checked |
Sets the initial state of the switch | boolean | false | true |
disabled |
Sets the accessibility state of the switch | boolean | false | true |
required |
Makes the switch a required field | boolean | false | true |
invalid |
Sets the validity of the switch | boolean | false | true |
labelPosition |
Sets the label postion of the switch | 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 |
The igc-switch should emit the following events:
| Name | Description | Type |
|---|---|---|
igcChange |
Emitted when the switch changes its checked state | - |
igcFocus |
Emitted when the switch gains focus | - |
igcBlur |
Emitted when the switch loses focus | - |
The igc-switch exposes the following methods:
| Name | Description | Arguments |
|---|---|---|
click |
Simulates a click on the switch. | - |
focus |
Sets focus on the switch. | options: FocusOptions |
blur |
Removes focus from the switch. | - |
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 |
| Name | Description |
|---|---|
| (default) | The switch label. |
| Name | Description |
|---|---|
| base | The base wrapper of the switch. |
| control | The switch control. |
| thumb | The position indicator of the switch. |
| label | The switch label. |
Automation
- Scenario 1: Should change the switch checked state correctly.
- Scenario 2: Should change the switch disabled state correctly.
- Scenario 3: Should set the switch required option correctly.
- Scenario 4: Should position the switch label correctly.
- Scenario 5: Should set the switch validity correctly.
- Scenario 6: Should emit event when the switch checked state changes.
- Scenario 7: Should emit events when the switch gains or loses focus.