3.0.0-alpha.4 Alpha
Light Dark Light Dark System Search /

Radio Group

<wa-radio-group> Since 2.0 stable

Radio groups are used to group multiple radios or radio buttons so they function as a single form control.

Option 1 Option 2 Option 3 
<wa-radio-group label="Select an option" name="a" value="1">
  <wa-radio value="1">Option 1</wa-radio>
  <wa-radio value="2">Option 2</wa-radio>
  <wa-radio value="3">Option 3</wa-radio>
</wa-radio-group>

Examples

Help Text

Add descriptive help text to a radio group with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Option 1 Option 2 Option 3 
<wa-radio-group label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
  <wa-radio value="1">Option 1</wa-radio>
  <wa-radio value="2">Option 2</wa-radio>
  <wa-radio value="3">Option 3</wa-radio>
</wa-radio-group>

Radio Buttons

Radio buttons offer an alternate way to display radio controls. In this case, an internal button group is used to group the buttons into a single, cohesive control.

Option 1 Option 2 Option 3 
<wa-radio-group label="Select an option" help-text="Select an option that makes you proud." name="a" value="1">
  <wa-radio-button value="1">Option 1</wa-radio-button>
  <wa-radio-button value="2">Option 2</wa-radio-button>
  <wa-radio-button value="3">Option 3</wa-radio-button>
</wa-radio-group>

Disabling Options

Radios and radio buttons can be disabled by adding the disabled attribute to the respective options inside the radio group.

Option 1 Option 2 Option 3 
<wa-radio-group label="Select an option" name="a" value="1">
  <wa-radio value="1">Option 1</wa-radio>
  <wa-radio value="2" disabled>Option 2</wa-radio>
  <wa-radio value="3">Option 3</wa-radio>
</wa-radio-group>

Sizing Options

The size of Radios and Radio Buttons will be determined by the Radio Group's size attribute. 

<wa-radio-group label="Select an option" size="medium" value="medium" class="radio-group-size">
  <wa-radio value="small">Small</wa-radio>
  <wa-radio value="medium">Medium</wa-radio>
  <wa-radio value="large">Large</wa-radio>
</wa-radio-group>

<script>
  const radioGroup = document.querySelector('.radio-group-size');

  radioGroup.addEventListener('wa-change', () => {
    radioGroup.size = radioGroup.value;
  });
</script>

Radios and Radio Buttons also have a size attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Radio Group.

Validation

Setting the required attribute to make selecting an option mandatory. If a value has not been selected, it will prevent the form from submitting and display an error message.

Option 1 Option 2 Option 3
Submit 
<form class="validation">
  <wa-radio-group label="Select an option" name="a" required>
    <wa-radio value="1">Option 1</wa-radio>
    <wa-radio value="2">Option 2</wa-radio>
    <wa-radio value="3">Option 3</wa-radio>
  </wa-radio-group>
  <br />
  <wa-button type="submit" variant="brand">Submit</wa-button>
</form>

<script>
  const form = document.querySelector('.validation');

  // Handle form submit
  form.addEventListener('submit', event => {
    event.preventDefault();
    alert('All fields are valid!');
  });
</script>

Custom Validity

Use the setCustomValidity() method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.

Not me Me neither Choose me
Submit 
<form class="custom-validity">
  <wa-radio-group label="Select an option" name="a" value="1">
    <wa-radio value="1">Not me</wa-radio>
    <wa-radio value="2">Me neither</wa-radio>
    <wa-radio value="3">Choose me</wa-radio>
  </wa-radio-group>
  <br />
  <wa-button type="submit" variant="brand">Submit</wa-button>
</form>

<script>
  const form = document.querySelector('.custom-validity');
  const radioGroup = form.querySelector('wa-radio-group');
  const errorMessage = 'You must choose the last option';

  // Set initial validity as soon as the element is defined
  customElements.whenDefined('wa-radio-group').then(() => {
    radioGroup.setCustomValidity(errorMessage);
  });

  // Update validity when a selection is made
  form.addEventListener('wa-change', () => {
    const isValid = radioGroup.value === '3';
    radioGroup.setCustomValidity(isValid ? '' : errorMessage);
  });

  // Handle form submit
  form.addEventListener('submit', event => {
    event.preventDefault();
    alert('All fields are valid!');
  });
</script>

Slots

Name Description
(default) The default slot where <wa-radio> or <wa-radio-button> elements are placed.
label The radio group's label. Required for proper accessibility. Alternatively, you can use the label attribute.
help-text Text that describes how to use the radio group. Alternatively, you can use the help-text attribute.

Properties

Name Description Reflects
label
label
The radio group's label. Required for proper accessibility. If you need to display HTML, use the label slot instead.
Type string
Default ''
helpText
help-text
The radio groups's help text. If you need to display HTML, use the help-text slot instead.
Type string
Default ''
name
name
The name of the radio group, submitted as a name/value pair with form data.
Type string | null
Default null
value
The current value of the radio group, submitted as a name/value pair with form data.
defaultValue
value
The default value of the form control. Primarily used for resetting the form control.
Type null | string
size
size
The radio group's size. This size will be applied to all child radios and radio buttons.
Type 'small' | 'medium' | 'large'
Default 'medium'
required
required
Ensures a child radio is checked before allowing the containing form to submit.
Type boolean
Default false
withLabel
with-label
Used for SSR. if true, will show slotted label on initial render.
Type boolean
Default false
withHelpText
with-help-text
Used for SSR. if true, will show slotted help text on initial render.
Type boolean
Default false
validationTarget
We use the first available radio as the validationTarget similar to native HTML that shows the validation popup on the first radio element.

Events

Name Description
wa-change Emitted when the radio group's selected value changes.
wa-input Emitted when the radio group receives user input.
wa-invalid Emitted when the form control has been checked for validity and its constraints aren't satisfied.

CSS parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label's wrapper.
form-control-input The input's wrapper.
form-control-help-text The help text's wrapper.
button-group The button group that wraps radio buttons.
button-group__base The button group's base part.

Dependencies

This component automatically imports the following elements. Subdependencies, if any exist, will also be included in this list.

Importing

The autoloader is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN npm React

To manually import this component from the CDN, use the following code.

import 'https://early.webawesome.com/webawesome@3.0.0-alpha.4/dist/components/radio-group/radio-group.js';
 Coming soon! Coming soon!
    No results