Single checkbox

Renders a single checkbox with a label.

The field ID is set to true or false depending on whether the checkbox is checked or not.

Single checkbox props

      fieldType: 'singleCheckbox',
      checkBoxLabelComponent: null, // Object with { componentClass, props }.
      // `componentClass` is the imported class of the component to replace the checkbox label.
      // `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.
      checkboxLabelMarkdown: null, // Markdown string - a markdown string to render as HTML TODO doc what addon is needed to use this and add to all the other labels.
      validatesOn: ['$inherited', 'checkboxToggled'], // Array of strings

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.

Single checkbox basic usage

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

const formSchema = {
  formSettings: {
    formName: 'singleCheckboxExample1',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldId: 'acceptTerms',
      fieldType: 'singleCheckbox',
      fieldLabel: 'I agree to the terms and conditions',
      checkBoxLabel: 'I agree to the terms and conditions',
    },
  ],
};

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

Single checkbox markdown checkbox label

You can also pass a markdown string to the checkboxLabelMarkdown prop. This will be rendered as HTML inside a label element.

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

const formSchema = {
  formSettings: {
    formName: 'singleCheckboxExample2',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldLabel: 'Terms and conditions',
      fieldId: 'acceptTerms',
      fieldType: 'singleCheckbox',
      checkboxLabelMarkdown: 'I agree to the __**[terms and conditions here](https://example.com)**__.',
    },
  ],
};

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

Single checkbox custom component for checkbox label

You can use a custom component for the checkbox label by passing checkBoxLabelComponent to the field. The component passed will then be rendered in place of the standard label element for each option.

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 key 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 ComponentForSingleCheckboxOption from '../forms/ComponentForSingleCheckboxOption';

const formSchema = {
  formSettings: {
    formName: 'singleCheckboxExample3',
    hideSubmitButton: true,
  },
  fields: [
    {
      fieldLabel: 'Terms and conditions',
      fieldId: 'acceptTerms',
      fieldType: 'singleCheckbox',
      checkBoxLabelComponent: {
        componentClass: ComponentForSingleCheckboxOption,
        props: {
          info: 'This text was passed to the label component dynamically for this option, via the checkBoxLabelComponent.props object.',
        },
      },
    },
  ],
};

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