Skip to content

Radio Specification

Stefan Ivanov edited this page Jul 21, 2021 · 3 revisions

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility

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

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

  1. Each radio button should be identifiable via a property, like name.
  2. Each radio button should represent a unit of information, like value.
  3. Each radio button should provide a way to be disabled.
  4. Each radio button should be interacted with via mouse and/or keyboard.
  5. Each radio button should be accessible.
  6. Each radio button should have an optional label.
  7. Each radio button should have a configurable label position - before or after.
  8. Each radio button should emit an event when it gains focus.
  9. Each radio button should emit an event when it loses focus.
  10. Each radio button should emit an event when its checked status changes.
  11. Each radio button should be able to report validation errors in the context of web forms.
  12. The radio group should provide an alignment option that renders radio buttons in column/row layout.
  13. The radio group should provide a way to be disabled.
  14. The radio group should set the label position of its radio buttons consistently to before or after.
  15. The radio group should provide a way to be a required form field.

Developer stories

  1. 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.
  2. 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.
  3. 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.
  4. As a developer, I want to be able to use the radio button in Web Forms as a regular input element of type radio.
  5. 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.
  6. As a developer, I want to be able to disable the radio button so that the user is not able to select that button.
  7. 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.
  8. 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.
  9. 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.
  10. As a developer, I want to be able to programmatically focus the radio button so that I can manually trigger focus.
  11. As a developer, I want to be able to programmatically blur the radio button so that I can manually trigger blur.
  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 radio button.
  13. 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.
  14. 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.
  15. 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

  1. As an end-user, I want to be able to identify if an individual radio button is disabled or not.
  2. 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.
  3. As an end-user, I want to be able to able to differentiate between selected and deselected radio buttons.
  4. As an end-user, I want to be able to identify the option I am selecting via label or some other visual aid.
  5. As an end-user, I want to be able to identify if my selection is invalid.
  6. As an end-user, I want to be able to identify if the radio group is disabled or not.
  7. 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.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 Reflected
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

Aria attributes set on the input control:

Clone this wiki locally