Radio button group

Renders a radio button group. The value of the field as a whole is the value property of the currently selected option.

Radio button group props

      fieldType: 'radioButtonGroup',
      options: [], // Array of objects, see /docs/radio-button-group#radio-button-group-options-prop
      optionLabelComponent: null, // Object with { componentClass, props }.
      // `componentClass` is the imported class of the component to replace the label element for each option.
      // `props` can be included to pass state or data to the component, accessible as {{@props}}.
      // `@option`, `@for`, `@labelId`, `@checked`, `@changesetWebform`, and `@formField` are also passed to the component.
      // Set `for={{@for}}` and `id={{@labelId}} on the label element in the component to ensure accessibility.
      validatesOn: ['$inherited', 'radioOptionChanged'], // Array of strings
      isFieldset: true, // Wrap field options in a fieldset element and field label in a legend element.

The above props are in addition to the generic field props shown with their default values below.

    validationRules: [], // Array of objects defining validation rules. See "Validation".
    validatesOn: ['submit', 'pushErrors'], // Array of strings, specifing the names of events which should triggger validation.
    showValidationWhenFocussed: null, // Boolean - unless this is true, validation colours, icons and messages will be omitted for as long as the "focussed" prop of a field is true. The build in input and textarea fields set focussed to true when the user focuesses the element.
    omitted: false, // Boolean - or object - if true, the field is omitted and also ignored when validating or submitting the form. Can also be an object which defines rules for dynamic omission/inclusion. See /docs/hiding-and-showing-fields.
    defaultValue: null, // Any - auto set the changeset property for the field to this value when the ChangesetWebform component is rendered and the changeset is created. This value will be overridden by a corresponding property in the data object that is passed to the ChangesetWebform component.
    labelComponent: null, // Object with { componentClass, props }.
    // If set, fieldLabel becomes null.
    // `componentClass` is the imported class of the component to show inside the field label element.
    // `props` can be included to pass state or data to the component, accessible as {{@props}}.
    // `@changesetWebform, and @formField are passed to the component.
    labelMarkdown: null, // String - a markdown string to render as HTML within the label element.
    hideLabel: null, // Boolean - Hide the label from the user
    disabled: false, // Boolean - disable the field, but do not hide it. It will still be validated [TODO check] and included when the form is submitted
    resetWhenOmitted: true, // Boolean - reset the field value and validation when the field is omitted from the form.
    attrsFromConfig: {
      classNames: {}, // Object - keys can correspond to those in the classNames settings. See /docs/configure-classnames
    },
    cloneActionsPosition: 'fieldActions', // String - where to place the remove clone button in relation to the cloned field. Can be [TODO]
    includeLabelForAttr: false, // Boolean - if true, the label element will have a 'for' attribute that matches the input element's 'id' attribute.
    isFieldset: false, // Boolean - if true, the field options are wrapped in a fieldset element, and the field label is wrapped in a legend element.
    requiresAriaLabelledBy: false, // Boolean - if true, the field will have an aria-labelledby attribute that points to the field label. This is not required if the field uses semantic element/s such as inputs or textareas, and the "for" attribute of the label correctly points to the semantic element/s.

Radio button group `options` prop

Each option in the options property of field with type radioButtonGroup can have the following properties.

    value: null, // Will be fieldValue when this option is checked.
    // One of label, optionLabelComponent or optionLabelMarkdown must be passed.
    label: null, // String to display as the label of the option.
    optionLabelComponent: null, // Optional. Component class to replace the standard label element for the option.
    optionLabelMarkdown: null, // Optional. Markdown content that will be rendered as HTML inside the label element for the option.

You can also pass a primitive value, such as a string or number as an option. In this case the option will be expanded into an object in which the values of the label and value properties will be the same.

The above props are in addition to the generic field props shown with their default values below.

    validationRules: [], // Array of objects defining validation rules. See "Validation".
    validatesOn: ['submit', 'pushErrors'], // Array of strings, specifing the names of events which should triggger validation.
    showValidationWhenFocussed: null, // Boolean - unless this is true, validation colours, icons and messages will be omitted for as long as the "focussed" prop of a field is true. The build in input and textarea fields set focussed to true when the user focuesses the element.
    omitted: false, // Boolean - or object - if true, the field is omitted and also ignored when validating or submitting the form. Can also be an object which defines rules for dynamic omission/inclusion. See /docs/hiding-and-showing-fields.
    defaultValue: null, // Any - auto set the changeset property for the field to this value when the ChangesetWebform component is rendered and the changeset is created. This value will be overridden by a corresponding property in the data object that is passed to the ChangesetWebform component.
    labelComponent: null, // Object with { componentClass, props }.
    // If set, fieldLabel becomes null.
    // `componentClass` is the imported class of the component to show inside the field label element.
    // `props` can be included to pass state or data to the component, accessible as {{@props}}.
    // `@changesetWebform, and @formField are passed to the component.
    labelMarkdown: null, // String - a markdown string to render as HTML within the label element.
    hideLabel: null, // Boolean - Hide the label from the user
    disabled: false, // Boolean - disable the field, but do not hide it. It will still be validated [TODO check] and included when the form is submitted
    resetWhenOmitted: true, // Boolean - reset the field value and validation when the field is omitted from the form.
    attrsFromConfig: {
      classNames: {}, // Object - keys can correspond to those in the classNames settings. See /docs/configure-classnames
    },
    cloneActionsPosition: 'fieldActions', // String - where to place the remove clone button in relation to the cloned field. Can be [TODO]
    includeLabelForAttr: false, // Boolean - if true, the label element will have a 'for' attribute that matches the input element's 'id' attribute.
    isFieldset: false, // Boolean - if true, the field options are wrapped in a fieldset element, and the field label is wrapped in a legend element.
    requiresAriaLabelledBy: false, // Boolean - if true, the field will have an aria-labelledby attribute that points to the field label. This is not required if the field uses semantic element/s such as inputs or textareas, and the "for" attribute of the label correctly points to the semantic element/s.

Basic usage

import React from 'react';
import ChangesetWebform from 'react-changeset-webforms/src/components/ChangesetWebform.jsx';

const formSchema = {
  formSettings: {
    formName: 'radioButtonGroupExample',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldId: 'rgbColours',
      fieldType: 'radioButtonGroup',
      fieldLabel: 'Select colour',
      attrsFromConfig: {
        classNames: {
          optionsWrapper: ['$inherited', 'd-flex'],
          labelledRadioButton: ['$inherited', 'me-4'],
        },
      },
      options: [
        {
          label: 'Red',
          value: 'ff0000',
        },
        {
          label: 'Green',
          value: '00ff00',
        },
        {
          label: 'Blue',
          value: '0000ff',
        },
      ],
    },
  ],
};

export default function RadioButtonGroupExampleOne() {
  const [currentValue, setCurrentValue] = React.useState(null);

  function onFieldValueChange(formField) {
    setCurrentValue(formField.fieldValue);
  }

  return (
    <>
      <ChangesetWebform
        formSchema={formSchema}
        onFieldValueChange={onFieldValueChange}
      />
      {currentValue && <div data-test-id="current-value">Selected colour: {currentValue}</div>}
    </>
  );
}

Option label content in markdown

Pass a string of markdown content as optionLabelmarkdown and it will be rendered inside the label element for the option.

import React from 'react';
import ChangesetWebform from 'react-changeset-webforms/src/components/ChangesetWebform.jsx';

const formSchema = {
  formSettings: {
    formName: 'radioButtonGroupExample3',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldId: 'rgbColours',
      fieldType: 'radioButtonGroup',
      fieldLabel: 'Select colour',
      attrsFromConfig: {
        classNames: {
          optionsWrapper: ['$inherited', 'd-flex'],
          labelledRadioButton: ['$inherited', 'me-4'],
        },
      },
      options: [
        {
          optionLabelMarkdown: '**Red**',
          value: 'ff0000',
        },
        {
          optionLabelMarkdown: '_Green_',
          value: '00ff00',
        },
      ],
    },
  ],
};

export default function RadioButtonGroupExampleThree() {
  const [currentValue, setCurrentValue] = React.useState(null);

  function onFieldValueChange(formField) {
    setCurrentValue(formField.fieldValue);
  }

  return (
    <>
      <ChangesetWebform
        formSchema={formSchema}
        onFieldValueChange={onFieldValueChange}
      />
      {currentValue && <div data-test-id="current-value">Selected colour: {currentValue}</div>}
    </>
  );
}

Option label content with a custom component

When using a custom component for option labels, either by:

passing optionLabelComponent to the field. The component passed will then be rendered in place of the standard label element for each option.
by passing labelComponent to a specific option. The component passed will then be rendered in place of the standard label element for that specific option, and will override optionLabelComponent.

In both cases the following applies, the object passed must take the following form.

{ componentClass: // Class, required. The imported class of the component to render. props: // Object, optional. This object that will be passed to the component as "props" }

The component template will have access to the boolean as well as the hash which includes the label and value props for that option.
Accessibility features
- Set for= on the label element, to ensure that the browser knows which radio button the label is for.
- Set id= so that the aria-labelledby attribute on the radio button works correctly.