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 a 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.
The radio group should set the label position of its radio buttons consistently to before or after.
The radio group should provide a way to be a required form field.

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 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 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 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 an individual 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.
As an end-user, I want to be able to identify if the radio group is disabled or not.
As an end-user, I want all radio buttons in a group to have consistent label alignment, so that they are easier to read.

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 to 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>

API

Properties
disabled - toggle element accessibility (enabled/disabled).
checked - set initial checked state of the element (true).
Events
change - triggered on change state change of the element.
focus - triggered on focus of the element (focus in).
blur - triggered when focus is moved away from the element.

3.3 API

3.3.1 Properties

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

Name	Description	Type	Default value
`name`	Sets the name of the radio button.	string	-
`value`	Sets the value of the radio button.	string	-
`checked`	Sets the checked state of the radio button.	Boolean	`false`
`disabled`	Sets the disabled state of the radio button.	Boolean	`false`
`disableRipple`	Disables the ripple effect.	Boolean	`false`
`focused`	Sets/gets whether the radio button is on focus.	Boolean	`false`
`invalid`	Sets the validity of the radio button.	Boolean	`false`
`label-position`	Sets the position of the label.	string	`after`
`required`	Sets/gets whether the radio button is required.	Boolean	`false`

3.3.2 Events

The igx-radio and the radio group directive emit the following event:

Name	Description	Type
`change`	Emitted when the radio button changes its checked state	-

3.3.3 Methods

The igx-radio exposes the following methods:

Name	Description	Arguments
`select`	Selects the current radio button.	-
`deselect`	Deselects the current radio button.	-
`writeValue`	Checks whether the provided value is consistent to the current radio button and returns a boolean result.	value:any

3.3.4 Accessors

The radio group directive has the following accessors:

Name	Description	Type	Default value
`name`	Sets/gets the name attribute of the radio group component. All child radio buttons inherits this name.	-	-
`value`	Sets/gets the value attribute.	-	-
`alignment`	Returns the alignment of the igx-radio-group.	-	-
`disabled`	Allows to disable the radio group.	Boolean	`false`
`selected`	Sets/gets the selected child radio button.	-	-
`label-position`	Sets/gets the position of the label in the child radio buttons.	string	`after`
`required`	Sets/gets whether the radio button is required.	Boolean	`false`