RadioGroup

A radio group is used to choose between a list of pre-defined options.

Uncontrolled Value

By default, the RadioGroup component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to check the radio by default.

<RadioGroup label='Do you like Convergo?' defaultValue='yes'>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no'>No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
>
  <Radio value="yes">
    Yes
  </Radio>
  <Radio value="no">
    No
  </Radio>
</RadioGroup>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [selected, setSelected] = useState('yes');

  return (
    <div>
      <RadioGroup
        label="Do you like Convergo?"
        value={selected}
        onChange={setSelected}
      >
        <Radio value="yes">Yes</Radio>
        <Radio value="no">No</Radio>
      </RadioGroup>

      <div>Selected: {selected}</div>
    </div>
  );
}

function Example() {
  const [selected, setSelected] = useState('yes');

  return (
    <div>
      <RadioGroup
        label="Do you like Convergo?"
        value={selected}
        onChange={setSelected}
      >
        <Radio value="yes">Yes</Radio>
        <Radio value="no">No</Radio>
      </RadioGroup>

      <div>Selected: {selected}</div>
    </div>
  );
}

function Example() {
  const [
    selected,
    setSelected
  ] = useState('yes');

  return (
    <div>
      <RadioGroup
        label="Do you like Convergo?"
        value={selected}
        onChange={setSelected}
      >
        <Radio value="yes">
          Yes
        </Radio>
        <Radio value="no">
          No
        </Radio>
      </RadioGroup>

      <div>
        Selected:{' '}
        {selected}
      </div>
    </div>
  );
}

Labeling

A RadioGroup component should be labeled with a visual text through the label prop. If the Radio does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
  labelPlacement="side start"
  orientation="horizontal"
>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
  labelPlacement="side start"
  orientation="horizontal"
>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
  labelPlacement="side start"
  orientation="horizontal"
>
  <Radio value="yes">
    Yes
  </Radio>
  <Radio value="no">
    No
  </Radio>
</RadioGroup>

Required

To indicate to the user that the RadioGroup is required you can use the isRequired prop.

<RadioGroup label='Do you like Convergo?' isRequired>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no'>No</Radio>
</RadioGroup>

<RadioGroup label='Do you like Convergo?' isRequired>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no'>No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  isRequired
>
  <Radio value="yes">
    Yes
  </Radio>
  <Radio value="no">
    No
  </Radio>
</RadioGroup>

Validation

The RadioGroup component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop. The error message will not be rendered to the user, since a radio group can only have an error that defines that it needs to be checked. However, it is still useful for screen readers and as such required to be passed in to make the RadioGroup invalid. Please localize the error message for internationalization.

function Example() {
  const [selected, setSelected] = useState();

  return (
    <div>
      <RadioGroup 
        label='Do you like Convergo?'
        value={selected} 
        onChange={setSelected}
        errorMessage={selected !== 'yes' && 'Yes field needs to be checked.'}
      >
        <Radio value='yes'>Yes</Radio>
        <Radio value='no'>No</Radio>
      </RadioGroup>

      <div>Selected: {selected}</div>
    </div>
  );
}

function Example() {
  const [selected, setSelected] = useState();

  return (
    <div>
      <RadioGroup
        label="Do you like Convergo?"
        value={selected}
        onChange={setSelected}
        errorMessage={selected !== 'yes' &&
          'Yes field needs to be checked.'}
      >
        <Radio value="yes">Yes</Radio>
        <Radio value="no">No</Radio>
      </RadioGroup>

      <div>Selected: {selected}</div>
    </div>
  );
}

function Example() {
  const [
    selected,
    setSelected
  ] = useState();

  return (
    <div>
      <RadioGroup
        label="Do you like Convergo?"
        value={selected}
        onChange={setSelected}
        errorMessage={selected !==
            'yes' &&
          'Yes field needs to be checked.'}
      >
        <Radio value="yes">
          Yes
        </Radio>
        <Radio value="no">
          No
        </Radio>
      </RadioGroup>

      <div>
        Selected:{' '}
        {selected}
      </div>
    </div>
  );
}

Description

The RadioGroup supports an optional description that further explains the purpose of the field.

function Example() {
  const [selected, setSelected] = useState();

  return (
    <div>
      <RadioGroup 
        label='Do you like Convergo?'
        value={selected} 
        onChange={setSelected}
        description='Some description.'
      >
        <Radio value='yes'>Yes</Radio>
        <Radio value='no'>No</Radio>
      </RadioGroup>

      <div>Selected: {selected}</div>
    </div>
  );
}

function Example() {
  const [selected, setSelected] = useState();

  return (
    <div>
      <RadioGroup 
        label='Do you like Convergo?'
        value={selected} 
        onChange={setSelected}
        description='Some description.'
      >
        <Radio value='yes'>Yes</Radio>
        <Radio value='no'>No</Radio>
      </RadioGroup>

      <div>Selected: {selected}</div>
    </div>
  );
}

function Example() {
  const [
    selected,
    setSelected
  ] = useState();

  return (
    <div>
      <RadioGroup
        label="Do you like Convergo?"
        value={selected}
        onChange={setSelected}
        description="Some description."
      >
        <Radio value="yes">
          Yes
        </Radio>
        <Radio value="no">
          No
        </Radio>
      </RadioGroup>

      <div>
        Selected:{' '}
        {selected}
      </div>
    </div>
  );
}

Contextual Help

To offer the user contextual help, the RadioGroup supports passing a contextualHelp prop, that accepts a ReactNode.

<RadioGroup
  label='Do you like Convergo?'
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no'>No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
>
  <Radio value="yes">
    Yes
  </Radio>
  <Radio value="no">
    No
  </Radio>
</RadioGroup>

Disabled

The Checkbox component can be disabled via the isDisabled prop.

<RadioGroup label='Do you like Convergo?' isDisabled>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no'>No</Radio>
</RadioGroup>

<RadioGroup label='Do you like Convergo?' isDisabled>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no'>No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  isDisabled
>
  <Radio value="yes">
    Yes
  </Radio>
  <Radio value="no">
    No
  </Radio>
</RadioGroup>

You can also make specific options in the RadioGroup disabled individually.

<RadioGroup label='Do you like Convergo?'>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no' isDisabled>No</Radio>
</RadioGroup>

<RadioGroup label='Do you like Convergo?'>
  <Radio value='yes'>Yes</Radio>
  <Radio value='no' isDisabled>No</Radio>
</RadioGroup>

<RadioGroup label="Do you like Convergo?">
  <Radio value="yes">
    Yes
  </Radio>
  <Radio
    value="no"
    isDisabled
  >
    No
  </Radio>
</RadioGroup>

Read Only

The Checkbox component can be marked as read only via the isReadOnly prop.

<RadioGroup label="Do you like Convergo?" defaultValue="yes" isReadOnly>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
  isReadOnly
>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>

<RadioGroup
  label="Do you like Convergo?"
  defaultValue="yes"
  isReadOnly
>
  <Radio value="yes">
    Yes
  </Radio>
  <Radio value="no">
    No
  </Radio>
</RadioGroup>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API