Radio Specification - IgniteUI/igniteui-webcomponents GitHub Wiki

Contents

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

Owned by

Team Name: Design and Web Development (DnD)

Developer: Simeon Simeonoff

Designer: Stefan Ivanov

Requires approval from

  • Diyan Dimitrov | Date:
  • Stefan Ivanov | Date: 21 Jul 2021

Signed off by

  • Product Owner: Radoslav Mirchev | Date:
  • Radoslav Karaivanov | Date:

Revision History

Version Users Date Notes
1 Simeon Simeonoff Date 16 Jul 2021 Initial Proposal

1. Overview

The igc-radio component renders a single radio button. Radio buttons aren't useful on their own and are usually a part of a bigger unit or group (see igc-radio-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 igc-radio button should also provide ways to set and get its validity when used in the context of Forms.

Acceptance criteria

  1. The radio button component should be identifiable via a property, like name.
  2. The radio button component should represent a unit of information, like value.
  3. The radio button component should provide a way to be disabled.
  4. The radio button component should provide a wat to be marked as required.
  5. The radio button component should be interacted with via mouse and/or keyboard.
  6. The radio button component should be accessible.
  7. The radio button component should have an optional label.
  8. The radio button component should provide accessibility hooks to specify a label.
  9. The radio button component should have configurable label position - before or after.
  10. The radio button component should emit an event when it gains focus.
  11. The radio button component should emit an event when it loses focus.
  12. The radio button component should emit an event when its checked status changes.
  13. The radio button component should be able to report validation errors in the context of web forms.

2. User Stories

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 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 required state of the radio button declaratively so that I can provide a validation error if no option is selected.
  9. 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.
  10. 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.
  11. As a developer, I want to be able to programmatically focus the radio button so that I can manually trigger focus.
  12. As a developer, I want to be able to programmatically blur the radio button so that I can manually trigger blur.
  13. 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.
  14. 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.
  15. 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.
  16. 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.
  17. As a developer, I want to be able to set aria-label in case I don't want to show a visual text label for a radio button.
  18. As a developer, I want to be able to set aria-labelledby in case I want to use another text element in the document as label.

End-user stories

  1. As an end-user, I want to be able to identify if a 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 the label of the radio button regardless of whether it's visible or not.

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 Standalone Usage:

<igc-radio name="fruit" value="apple" checked>Apple</igc-radio>
<igc-radio name="fruit" value="orange">Orange</igc-radio>

3.2.2 Group Usage:

<igc-radio-group>
  <igc-radio name="fruit" value="apple" checked>Apple</igc-radio>
  <igc-radio name="fruit" value="banana">Banana</igc-radio>
  <igc-radio name="fruit" value="mango">Mango</igc-radio>
  <igc-radio name="fruit" value="orange" disabled>Orange</igc-radio>
</igc-radio-group>

3.3 API

3.3.1 Properties

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

Name Description Type Default value Reflected
name Sets the name of the radio button. string - false
value Sets the value of the radio button. string - false
checked Sets the checked state of the radio button. Boolean false true
disabled Sets the disabled state of the radio button. Boolean false true
required Sets the required state of the radio button. Boolean false true
invalid Sets the validity of the radio button. Boolean false true
labelPosition Sets the position of the label. 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
3.3.2 Events

The igc-radio emits the following events:

Name Description Type
igcFocus Emitted when the radio button gains focus. -
igcBlur Emitted when the radio button loses focus. -
igcChange Emitted when the radio button changes its checked state -
3.3.3 Methods

The igc-radio exposes the following methods:

Name Description Arguments
click Simulates a click on the radio button. -
focus Sets the radio on focus. options: FocusOptions
blur Removes the focus from the radio -
reportValidity Checks for validity and shows a validation message if the component is invalid. -
setCustomValidity Sets a custom validation message. If the message is not empty, the field will be considered invalid. message: string
3.3.4 Slots
Name Description
(default) The radio label.
3.3.5 CSS Parts
Name Description
base The radio button base wrapper.
control The radio button control.
label The radio button label.

4. Test Scenarios

TBD

5. Accessibility

Aria attributes set on the input control:

⚠️ **GitHub.com Fallback** ⚠️