Switch Specification

Owned by

Team Name: Phoenix

Developer: Zdravko Kolev

Designer: Stefan Ivanov

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 Draft
2	Stefan Ivanov, Silvia Ivanova	Date 20 Jul 2021	Rewrite for completeness

1. Overview

The <igx-switch> component is used to provide a capability for making a binary choice of a single settings option.

Objectives

It is providing API for the most common use cases when it comes make a binary choice for a certain condition.

Acceptance criteria

The switch component should have a toggle visual representation.
The switch component should have a clickable element and label.
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.

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 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 place content between the opening and closing brackets of the switch component, so that it can be used as a corresponding label.
Story 5: As a developer, I want to be able to specify the default state of the switch - checked or unchecked.
Story 6: As a developer, I want to be able to disable the switch, so that the user cannot change its state.
Story 7: As a developer, I want to be able to use the switch in a form, so that the user can provide binary information with it.
Story 8: 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 9: 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 10: As a developer, I want to be able to programmatically focus the switch, so that I can manually trigger the focus event.
Story 11: As a developer, I want to be able to programmatically blur the switch, so that I can manually trigger the blur event.
Story 12: 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 13: 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 14: 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 15: 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. Functionality

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 control as well as its own. 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

Defining a switch:

<igx-switch [(ngModel)]="user.subscribed">
  Subscribed
</igx-switch>

Using a switch in a form:

<form (submit)="saveForm()">
    <div *ngFor="let item of order.items">
         <ig-switch [disabled]="order.completed || order.canceled"
             [checked]="order.completed"
             [(ngModel)]="item.completed">
             {{ item.description }}
         </ig-switch>
    </div>
</form>

3.3. API

Properties

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

Name	Description	Type	Default value	Reflected
`name`	set the name of the switch	string	-	-
`value`	set the value of the switch	string	-	-
`disabled`	toggle element accessibility state	boolean	-	`false`
`checked`	set initial state of the switch	boolean	-	`false`
`focused`	set/get whether the switch component is on focus	boolean	-	`false`
`disableRipple`	enables/disables the ripple effect	boolean	-	`false`
`labelPosition`	set/get the position of the label in the switch component	string	`after`	-
`required`	set/get whether the switch is required for validation	boolean	-	`false`

Events

The igx-switch should emit the following events:

Name	Description	Type
`change`	triggered on toggle state change of the element	-
`focus`	triggered on focus of the element (focus in)	-
`blur`	triggered when focus is moved away from the element	-