Checkbox group

Renders a checkbox group. The value of the field as a whole is an array which will include the value of key for each option that is currently selected.

      fieldType: 'checkboxGroup',
      options: [], // Array of objects, docs/checkbox-group#checkbox-group-options.
      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', 'checkboxToggled'], // 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.

Checkbox group options

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

      fieldType: 'checkboxGroup',
      options: [], // Array of objects, docs/checkbox-group#checkbox-group-options.
      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', 'checkboxToggled'], // Array of strings
      isFieldset: true, // Wrap field options in a fieldset element and field label in a legend element.

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 key 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 ChangesetWebform from 'react-changeset-webforms/src/components/ChangesetWebform.jsx';

const formSchema = {
  formSettings: {
    formName: 'checkboxGroupExample1',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldId: 'checkboxes1',
      fieldType: 'checkboxGroup',
      fieldLabel: 'Basic usage',
      options: [
        {
          label: 'Option 1',
          key: '1',
        },
        {
          label: 'Option 2',
          key: '2',
        },
        {
          label: 'Option 3',
          key: '3',
        },
      ],
    },
  ],
};

export default function CheckboxGroupExampleOne() {
  return <ChangesetWebform formSchema={formSchema} />;
}

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 ChangesetWebform from 'react-changeset-webforms/src/components/ChangesetWebform.jsx';

const formSchema = {
  formSettings: {
    formName: 'checkboxGroupExample3',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldId: 'checkboxes3',
      fieldType: 'checkboxGroup',
      fieldLabel: 'Custom label components',
      options: [
        {
          key: 'Option 1',
          optionLabelMarkdown: '**Option 1**',
        },
        {
          key: 'Option 2',
          optionLabelMarkdown: '_Option 2_',
        },
      ],
    },
  ],
};

export default function CheckboxGroupExampleThree() {
  return <ChangesetWebform formSchema={formSchema} />;
}

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, key, and onlyCheckedOption props for that option.
Accessibility features
- Set for= on the label element, to ensure that the browser knows which checkbox the label is for.
- Set id= so that the aria-labelledby attribute on the checkbox works correctly.

import ChangesetWebform from 'react-changeset-webforms/src/components/ChangesetWebform.jsx';
import ComponentForAllCheckboxOptions from '../forms/ComponentForAllCheckboxOptions.jsx';
import ComponentForSingleCheckboxOption from '../forms/ComponentForSingleCheckboxOption.jsx';

const formSchema = {
  formSettings: {
    formName: 'checkboxGroupExample2',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldId: 'checkboxes2',
      fieldType: 'checkboxGroup',
      fieldLabel: 'Custom label components',
      optionLabelComponent: {
        componentClass: ComponentForAllCheckboxOptions,
        props: {
          infoLink: 'https://example.com',
        },
      },
      options: [
        {
          label: 'Option 1',
          key: '1',
        },
        {
          label: 'Option 2',
          key: '2',
        },
        {
          label: 'Option 3',
          key: '3',
          optionLabelComponent: {
            componentClass: ComponentForSingleCheckboxOption,
            props: {
              info: 'This text was passed to the label component dynamically for this option, via the optionLabelComponent.props object.',
            },
          },
        },
      ],
    },
  ],
};

export default function CheckboxGroupExampleTwo() {
  return <ChangesetWebform formSchema={formSchema} />;
}

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.