# auro-radio-group
The `auro-radio-group` element is used to group a set `auro-radio` elements.
## Properties
| Property | Attribute | Type | Default | Description |
|---------------------------------|---------------------------------|--------------------------|-------------|--------------------------------------------------|
| [appearance](#appearance) | `appearance` | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. |
| [disabled](#disabled) | `disabled` | `boolean` | | If true, all radio buttons will be disabled. |
| [error](#error) | `error` | `string` | | If true, sets persistent validity to `customError` and sets `setCustomValidity` = attribute value. |
| [horizontal](#horizontal) | `horizontal` | `boolean` | | If true, displays radio buttons horizontally. |
| [noValidate](#noValidate) | `noValidate` | `boolean` | | If true, disables auto-validation on blur. |
| [onDark](#onDark) | `onDark` | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. |
| [optionSelected](#optionSelected) | `optionSelected` | `object` | | Specifies the current selected radio button. |
| [required](#required) | `required` | `boolean` | | Populates the `required` attribute on the element. Used for client-side validation. |
| [setCustomValidity](#setCustomValidity) | `setCustomValidity` | `string` | | Sets a custom help text message to display for all validityStates. |
| [setCustomValidityCustomError](#setCustomValidityCustomError) | `setCustomValidityCustomError` | `string` | | Custom help text message to display when validity = `customError`. |
| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `string` | | Custom help text message to display when validity = `valueMissing`. |
| [validity](#validity) | `validity` | `string` | | Specifies the `validityState` this element is in. |
| [value](#value) | `value` | `string` | | Specifies the current value of the selected radio button. |
## Methods
| Method | Type | Description |
|------------|----------------------------------------|--------------------------------------------------|
| [reset](#reset) | `(): void` | Resets component to initial state. |
| [validate](#validate) | `(force?: boolean \| undefined): void` | Validates value.
**force**: Whether to force validation. |
## Events
| Event | Type | Description |
|-----------------------------|--------------------|--------------------------------------------------|
| `auroFormElement-validated` | | Notifies that the element has been validated. |
| [input](#input) | `CustomEvent` | Notifies every time the value prop of the element is changed. |
## Slots
| Name | Description |
|-----------------|--------------------------------------------------|
| [helpText](#helpText) | Allows for the helper text to be overridden. |
| [legend](#legend) | Allows for the legend to be overridden. |
| [optionalLabel](#optionalLabel) | Allows overriding the optional display text "(optional)", which appears next to the label. |
## CSS Shadow Parts
| Part | Description |
|---------------|--------------------------------------------------|
| `radio-group` | Apply css to the fieldset element in the shadow DOM |
# auro-radio
The `auro-radio` element is used to a button that allows the user to select one option from a set.
## Properties
| Property | Attribute | Type | Default | Description |
|--------------|--------------|--------------------------|-------------|--------------------------------------------------|
| [appearance](#appearance) | `appearance` | `'default' \| 'inverse'` | "'default'" | Defines whether the component will be on lighter or darker backgrounds. |
| [checked](#checked) | `checked` | `boolean` | | If set to true, the radio button will be filled. |
| [disabled](#disabled) | `disabled` | `boolean` | | If set to true, the radio button will be non-clickable. |
| [error](#error) | `error` | `boolean` | | If set to true, sets an error state on the radio button. |
| [id](#id) | `id` | `string` | | The id global attribute defines an identifier (ID) which must be unique in the whole document. |
| [label](#label) | `label` | `string` | | Label for the radio button. |
| [name](#name) | `name` | `string` | | Name for the radio button group. |
| [onDark](#onDark) | `onDark` | `boolean` | | DEPRECATED - use `appearance="inverse"` instead. |
| [required](#required) | `required` | `boolean` | | Defines element as required. |
| [value](#value) | `value` | `string` | | The value of the radio button. |
## Methods
| Method | Type | Description |
|---------|------------|------------------------------------|
| [reset](#reset) | `(): void` | Resets component to initial state. |
## Events
| Event | Type | Description |
|----------------------|--------------------|--------------------------------------------------|
| `auroRadio-blur` | `CustomEvent` | Notifies that the component has lost focus. |
| `auroRadio-selected` | `CustomEvent` | Notifies that the component has been marked as checked/selected. |
| [change](#change) | `CustomEvent` | (Deprecated) Notifies when checked value is changed. |
| [focusSelected](#focusSelected) | `CustomEvent` | Notifies that the component has gained focus. |
| [input](#input) | `InputEvent` | Notifies when when checked value is changed by user's interface. |
| [resetRadio](#resetRadio) | `CustomEvent` | Notifies that the component has reset the checked/selected state. |
| [toggleSelected](#toggleSelected) | `CustomEvent` | Notifies that the component has toggled the checked/selected state. |
## CSS Shadow Parts
| Part | Description |
|---------------|-------------------------------------------|
| [radio](#radio) | apply css to a specific checkbox. |
| `radio-input` | apply css to a specific checkbox's input. |
| `radio-label` | apply css to a specific checkbox's label. |
## Basic Radio
See code
```html
```
## Basic Radio Group
See code
```html
Form label goes here
```
## Property & Attribute Examples
### Appearance on Dark Backgrounds
Use the `appearance="inverse"` attribute to render the radio for use on dark backgrounds.
See code
```html
```
See code
```html
Form label goes here
```
### Checked
Use the `checked` attribute to pre-select a `` element.
Form label goes here
Yes
No
Maybe
See code
Form label goes here
Yes
No
Maybe
Form label goes here
Yes
No
Maybe
See code
Form label goes here
Yes
No
Maybe
### Disabled
Use the `disabled` attribute to disable singular `` elements or the entire ``.
Form label goes here
Form label goes here
See code
```html
Form label goes here
Form label goes here
```
Form label goes here
Form label goes here
See code
Form label goes here
Form label goes here
### Error
Use the `error` attribute to apply a persistent custom error that supersedes the HTML5 validation logic.
A custom error message can be set using the `error` attribute, or it can be used in conjunction with the `setCustomValidityCustomError` attribute.
See code
```html
Form label goes here
```
See code
Form label goes here
### Horizontal Group
Using the `horizontal` attribute will render the `auro-radio` elements in a horizontal line.
**Note**: Using the horizontal attribute has a limit of 3 options. Beyond three, options will be listed in vertically.
See code
```html
Form label goes here
```
### Required
When present, the `required` attribute specifies that an `` within the `` must be checked. There is no error message associated with the `required` attribute by default. Use `setCustomValidityValueMissing` to set a custom error message.
See code
```html
Form label goes here
```
## Method Examples
### Reset State
Use the `reset()` method to reset the ``'s `value` and `validity` state. Doing so will preserve all other attributes and properties.
Reset
Form label goes here
See code
```html
Reset
Form label goes here
```
```js
export function resetStateExample() {
const elem = document.querySelector('#resetStateExample');
document.querySelector('#resetStateBtn').addEventListener('click', () => {
elem.reset();
});
}
```
## Slot Examples
### Optional Label
The `` supports an `optionalLabel` slot, where users can can override the default `(optional)` notification text.
Form label goes here
(add custom label here)
See code
```html
Form label goes here
(add custom label here)
```
## Common Usage Patterns & Functional Examples
### Dynamic Example
This example demonstrates a data drive approach to rendering `` buttons.
**Note**: When dynamically creating `` elements, make sure to add an `id` attribute, as it is a required part of the HTML5 spec for all form elements.
See code
```html
Form label goes here
```
```js
export function dynamicExample() {
const values = ['Yes', 'No', 'Maybe'];
const radioGroup = document.getElementById('dynamicExample');
for (let i = 0; i < values.length; i++) {
const radio = document.createElement('auro-radio');
radio.id = `dynamicRadio${i}`;
radio.label = values[i];
radio.name = 'radioDemo';
radio.value = values[i];
radio.textContent = values[i];
radioGroup.appendChild(radio);
}
}
```
### Multiline Label
Example to show text wrapping on multiline labels.
See code
```html
Form label goes here
```
### Accordion Nested Group
This example shows how to use `` with the `` and `` elements for
nested/optional groups (such as a "More Options" section in a payment processor).
Accordion Test
More payment options
See code
```html
Accordion Test
More payment options
```
## Restyle Component with CSS Variables
The component may be restyled by changing the values of the following token(s).
```scss
@use "@aurodesignsystem/design-tokens/dist/themes/alaska/SCSSVariables--alaska" as v;
:host {
// auro-radio-group colors
--ds-auro-radio-group-label-color: inherit;
// auro-radio colors
--ds-auro-radio-btn-border-color: var(--ds-basic-color-border-bold, #{v.$ds-basic-color-border-bold});
--ds-auro-radio-btn-fill-color: transparent;
--ds-auro-radio-btn-inset-color: transparent;
--ds-auro-radio-label-color: inherit;
--ds-auro-radio-tap-color: transparent;
}
```