Radio 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 02 Feb 2017	Initial Draft
2	Stefan Ivanov and Simeon Simeonov	Date 20 Jul 2021	Rewrite for completeness

1. Overview

The igx-radio component renders a group of radio buttons.

Objectives

Provide an API for the most common use cases when selecting an option from a set of available options. The igx-radio button should also provide ways to set and get its validity when used in the context of Web Forms.

Acceptance criteria

Each radio button should be identifiable via a property, like name.
Each radio button should represent a unit of information, like value.
Each radio button should provide a way to be disabled.
Each radio button should be interacted with via mouse and/or keyboard.
Each radio button should be accessible.
Each radio button should have an optional label.
Each radio button should have configurable label position - before or after.
Each radio button should emit an event when it gains focus.
Each radio button should emit an event when it loses focus.
Each radio button should emit an event when its checked status changes.
Each radio button should be able to report validation errors in the context of web forms.
The radio group should provide an alignment option that renders radio buttons in column/row layout.
The radio group should provide a way to be disabled.

2. User Stories

Developer stories

As a developer, I want to be able to name the radio button so that I can easily identify it in when used with other buttons of the same type.
As a developer, I want to be able to set the value of the radio button so that I can associate a piece of information with a it.
As a developer, I want to be able to put text between the opening and closing brackets of the radio button so that it can be used as a label.
As a developer, I want to be able to use the radio button in Web Forms as a regular input element of type radio.
As a developer, I want to be able to position the label of the radio button either before or after the radio control so that it better suits my design.
As a developer, I want to be able to disable the radio button so that the user is not able to select that button.
As a developer, I want to be able to change the checked state of the radio button declaratively so that the button is selected at initialization.
As a developer, I want to be able to change the invalid state of the radio button declaratively so that I set set its validity at initialization.
As a developer, I want to be able to programmatically click the radio button so that I can interact with it via means other than a computer mouse.
As a developer, I want to be able to programmatically focus the radio button so that I can manually trigger focus.
As a developer, I want to be able to programmatically blur the radio button so that I can manually trigger blur.
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 radio button.
As a developer, I want to be able to check the validity of the radio button so that I can handle form errors and/or warnings.
As a developer, I want to be able to set a custom validation message so that the users of the radio button can easily identify and fix form errors and/or warnings.
As a developer, I want to be able to customize the appearance of the radio button so that it better fits the design language of my application.

End-user stories

As an end-user, I want to be able to identify if a radio button is disabled or not.
As an end-user, I want to be able to select a radio button in a group of other buttons via the arrow and tab keys on my keyboard or my computer mouse.
As an end-user, I want to be able to able to differentiate between selected and deselected radio buttons.
As an end-user, I want to be able to identify the option I am selecting via label or some other visual aid.
As an end-user, I want to be able to identify if my selection is invalid.

3. Functionality

3.1. End-User Experience

The radio button component is small and circular in shape. When selected it is represented by a concentric circle with two rings where the inner ring is filled. A deselected radio button is represented by a single outlined circle. The radio button can have an optional label that makes it easy do identify when used in a radio group. The user can click on either the circle or the label to select the radio button. Navigating between radio buttons in a group using the arrow keys on a keyboard also changes the currently selected radio button.

3.2. Developer Experience

3.2.1 Creating a radio group:

<igx-radio *ngFor="let item of ['Foo', 'Bar', 'Baz']" 
    value="{{item}}" name="group" 
    [(ngModel)]="user.favouriteVarName">{{item}}
</igx-radio>

Attaching change event example:

<igx-radio
    value="{{user.id}}"
    tabIndex="50"
    (change)="doAlert($event)"
    (focus)="doAlert($event)"
    (blur)="doAlert($event)"
    [(ngModel)]="user.favouriteVarName">
    {{user.name}}
</igx-radio>