@ea-lab/reactive-json-docs/public/rjbuild/docs/core/element/form/CheckBoxField.yaml

Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides

renderView:
  - type: Markdown
    content: |
      # CheckBoxField

      The `CheckBoxField` component provides checkbox and radio button groups with automatic data synchronization. It supports single selection (radio buttons or single checkbox), multiple selection (multiple checkboxes), and flexible data storage formats.

  - type: Markdown
    content: |
      ## Basic Syntax

      ```yaml
      - type: CheckBoxField
        dataLocation: ~.preferences
        label: "Select your preferences:"
        options:
          - label: "Option 1"
            value: "opt1"
          - label: "Option 2"
            value: "opt2"
          - label: "Option 3"
            value: "opt3"
      ```

      ## Properties

  - type: DefinitionList
    content:
      - term:
          code: dataLocation
          after: "(string, optional)"
        details: "Path to bind the field value in the data context."
      - term:
          code: defaultFieldValue
          after: "(any, optional)"
        details: "Default value when no data is present."
      - term:
          code: label
          after: "(string or View props, optional)"
        details: "Field label text (supports template evaluation and View component rendering)."
      - term:
          code: options
          after: "(array, optional)"
        details:
          type: Markdown
          content: |
            Static array of option objects, each with:
            - `label` (string, optional): Display text for the option (supports template evaluation)
            - `value` (any, required): Value stored when this option is selected
            - `attributes` (object, optional): Attributes applied to the option's container div
      - term:
          code: dynamicOptions
          after: "(string, optional)"
        details:
          type: Markdown
          content: "Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided."
      - term:
          code: controlType
          after: "(string, optional)"
        details: "Type of control - `\"checkbox\"` (default) or `\"radio\"`."
      - term:
          code: multiple
          after: "(boolean, optional)"
        details: "Whether multiple selections are allowed. Defaults to `true` if more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`."
      - term:
          code: attributes
          after: "(object, optional)"
        details: "Attributes applied to the wrapper div (or container div if no wrapper)."
      - term:
          code: inputAttributes
          after: "(object, optional)"
        details: "Attributes applied directly to each input element."
      - term:
          code: labelAttributes
          after: "(object, optional)"
        details: "Attributes applied to the main label (htmlFor is automatically managed)."
      - term:
          code: forceWrapper
          after: "(boolean, optional)"
        details: "Forces the presence (true) or absence (false) of the wrapper div. If omitted, wrapper is automatic only if label is present."
      - term:
          code: actions
          after: "(array, optional)"
        details: "Actions to execute based on field state."

  - type: Markdown
    content: |
      ## Data Management

      The component automatically synchronizes its value with the global data context. The data format depends on the selection mode:

      - **Radio buttons**: Stores a single value (the selected option's value)
      - **Single checkbox**: Stores a boolean (`true`) or the option's value when checked, `false` when unchecked
      - **Multiple checkboxes**: Stores an array of selected option values

      When `dataLocation` is used, the value is stored at the specified path. Without `dataLocation`, the value is stored in the template context using the component's `datafield`.

      ## Selection Modes

      ### Radio Buttons (Single Selection)

      Radio buttons allow only one selection at a time. Set `controlType: "radio"`:

      **Data stored**: Single value (e.g., `"credit"`)

      ### Single Checkbox

      A single checkbox stores a boolean or the option's value:

      **Data stored**: `true` when checked, `false` when unchecked (or the option's value if different from `true`)

      ### Multiple Checkboxes

      Multiple checkboxes allow selecting several options simultaneously:

      **Data stored**: Array of selected values (e.g., `["tech", "music"]`)

  - type: RjBuildDescriber
    title: "Basic Checkbox Group"
    description: "Simple multiple selection checkbox group"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.preferences
          label: "Select your preferences:"
          options:
            - label: "Email notifications"
              value: "email"
            - label: "SMS notifications"
              value: "sms"
            - label: "Push notifications"
              value: "push"
        - type: div
          attributes:
            style:
              marginTop: "20px"
              padding: "10px"
              borderRadius: "5px"
          content:
            - type: strong
              content: "Selected: "
            - ~.preferences
      data:
        preferences: []

  - type: RjBuildDescriber
    title: "Radio Button Group"
    description: "Single selection using radio buttons"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.size
          label: "Select size:"
          controlType: "radio"
          options:
            - label: "Small"
              value: "small"
            - label: "Medium"
              value: "medium"
            - label: "Large"
              value: "large"
            - label: "Extra Large"
              value: "xl"
        - type: div
          attributes:
            style:
              marginTop: "20px"
              padding: "10px"
              borderRadius: "5px"
          content:
            - type: strong
              content: "Selected size: "
            - ~.size
      data:
        size: ""

  - type: RjBuildDescriber
    title: "Dynamic Options"
    description: "Options provided via template evaluation using dynamicOptions"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.selectedItems
          label: "Select items:"
          dynamicOptions: ~.availableItems
      data:
        availableItems:
          - label: "Item 1"
            value: "item1"
          - label: "Item 2"
            value: "item2"
          - label: "Item 3"
            value: "item3"
          - label: "Item 4"
            value: "item4"
        selectedItems: []


  - type: Markdown
    content: |
      ## Advantages

      - **Flexible selection modes**: Supports radio buttons, single checkbox, and multiple checkboxes
      - **Automatic data synchronization**: Values are automatically stored in the correct format
      - **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
      - **Per-option customization**: Each option can have its own attributes
      - **Label flexibility**: Supports both simple strings and View component rendering
      - **Wrapper control**: Flexible wrapper system for styling control
      - **Accessibility**: Automatic label association with htmlFor attributes
      - **Empty state handling**: Gracefully handles empty options

      ## Limitations

      - No built-in validation beyond HTML5 checkbox/radio validation
      - No support for option grouping (use multiple CheckBoxField components)
      - Styling must be provided via external CSS or style attributes
      - Options must be provided as an array; empty arrays result in no rendering
      - For radio buttons, `multiple` is automatically set to `false` regardless of the `multiple` property

templates: {}
data: {}