-
Notifications
You must be signed in to change notification settings - Fork 161
Radio Specification
Team Name: Phoenix
Developer: Zdravko Kolev
Designer: Stefan Ivanov
- Product Owner: Radoslav Mirchev | Date:
- Radoslav Karaivanov | Date:
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.
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.
- 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
orafter
. - 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
orafter
. - The radio group should provide a way to be a required form field.
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
, andchange
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.
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.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>
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.
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 |
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 | - |
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 |
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: