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

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

renderView:
  - type: Markdown
    content: |
      # CheckBoxField

      The `CheckBoxField` component renders checkbox or radio button groups using React Bootstrap. It supports both single and multiple selections, dynamic options, and intelligent data storage based on the control type and configuration.

      ## 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: options
          after: "(array, optional)"
        details:
          type: Markdown
          content: "Static array of option objects with `label` and `value` properties."
      - term:
          code: dynamicOptions
          after: "(string, optional)"
        details:
          type: Markdown
          content: "Template path to dynamic options array."
      - term:
          code: controlType
          after: "(string, optional)"
        details: "Type of control - `checkbox` (default) or `radio`."
      - term:
          code: multiple
          after: "(boolean, optional)"
        details: "Force array storage for checkboxes (default: auto-detected)."
      - term:
          code: attributes
          after: "(object, optional)"
        details: "Attributes applied to the Form.Group container."
      - term:
          code: actions
          after: "(array, optional)"
        details: "Actions to execute based on field state."

  - type: Markdown
    content: |
      ## Option Format

      Each option object must have:
      - `label` (string|object): Display text or Reactive-JSON content for the option
      - `value` (any): The actual value to store when selected
      - `attributes` (object, optional): Additional attributes for the specific option

      ## Data Storage Modes

      The component uses different data storage strategies:

      ### Single Value Mode
      - Used for radio buttons (`controlType: "radio"`)
      - Used for single checkbox when `options.length === 1` and `multiple` is not set
      - Stores the selected value directly

      ### Array Mode
      - Used for multiple checkboxes when `options.length > 1` or `multiple: true`
      - Stores selected values in an array
      - Automatically manages array additions and removals

  - type: RjBuildDescriber
    title: "Multiple Checkboxes"
    description: "CheckBoxField with multiple options storing values in an array"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.interests
          options:
            - label: "Technology"
              value: "tech"
            - label: "Sports"
              value: "sports"
            - label: "Music"
              value: "music"
            - label: "Travel"
              value: "travel"
      data:
        interests:
          - sports
          - travel

  - type: RjBuildDescriber
    title: "Radio Buttons"
    description: "CheckBoxField as radio buttons for single selection"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.priority
          controlType: "radio"
          options:
            - label: "Low"
              value: "low"
            - label: "Medium"
              value: "medium"
            - label: "High"
              value: "high"
            - label: "Critical"
              value: "critical"
        - type: div
          content:
            - "Selected priority: "
            - type: strong
              content: ~.priority
      data:
        priority: ""

  - type: RjBuildDescriber
    title: "Single Checkbox"
    description: "Single checkbox for boolean values"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.acceptTerms
          options:
            - label: "I accept the terms and conditions"
              value: true
        - type: CheckBoxField
          dataLocation: ~.newsletter
          options:
            - label: "Subscribe to newsletter"
              value: true
        - type: div
          attributes:
            style:
              marginTop: "20px"
              padding: "10px"
              backgroundColor: "#f8f9fa"
              borderRadius: "5px"
          content:
            - type: strong
              content: "Current Values:"
            - type: div
              content:
                - "Terms accepted: "
                - type: span
                  content: "✓ Yes"
                  attributes:
                    style:
                      color: "green"
                  actions:
                    - what: hide
                      when: ~.acceptTerms
                      isNot: true
                - type: span
                  content: "✗ No"
                  attributes:
                    style:
                      color: "red"
                  actions:
                    - what: hide
                      when: ~.acceptTerms
                      is: true
            - type: div
              content:
                - "Newsletter: "
                - type: span
                  content: "✓ Yes"
                  attributes:
                    style:
                      color: "green"
                  actions:
                    - what: hide
                      when: ~.newsletter
                      isNot: true
                - type: span
                  content: "✗ No"
                  attributes:
                    style:
                      color: "red"
                  actions:
                    - what: hide
                      when: ~.newsletter
                      is: true
      data:
        acceptTerms: false
        newsletter: false

  - type: Markdown
    content: |
      ## Value Types Limitations

      **Important**: CheckBoxField has limitations with non-string value types due to HTML input behavior:

      - ✅ **String values**: Work perfectly (`"tech"`, `"sports"`, etc.)
      - ✅ **Boolean values**: Work for single checkboxes (`true`/`false`)  
      - ❌ **Numeric values**: May cause issues due to string conversion in HTML inputs
      - ❌ **Complex objects**: Not supported in array mode

      **Recommendation**: Use string values for reliability. Numeric and complex value type support may be improved in future versions.

      ```yaml
      # ✅ Recommended - String values
      options:
        - label: "Priority 1"
          value: "priority_1"
        - label: "Priority 2" 
          value: "priority_2"

      # ❌ Avoid - Numeric values may cause issues
      options:
        - label: "Priority 1"
          value: 1
        - label: "Priority 2"
          value: 2
      ```

  - type: RjBuildDescriber
    title: "Dynamic Options"
    description:
      type: Markdown
      content: |
        CheckBoxField with conditional display using `dynamicOptions` and `hide` actions.
        
        **Technique**: Since dynamic path selection like `~.data[~.key]` is not supported, 
        we create one CheckBoxField per category and use conditional `hide` actions to show 
        only the relevant one based on the selection.
    toDescribe:
      renderView:
        - type: SelectField
          dataLocation: ~.selectedCategory
          label: "Select Category to see available skills:"
          options:
            - label: "Choose category"
              value: ""
            - label: "Technology"
              value: "technology"
            - label: "Business"
              value: "business"
            - label: "Creative"
              value: "creative"
        - type: CheckBoxField
          dataLocation: ~.techSkills
          dynamicOptions: ~.skillCategories.technology
          actions:
            - what: hide
              when: ~.selectedCategory
              isNot: "technology"
        - type: CheckBoxField
          dataLocation: ~.businessSkills
          dynamicOptions: ~.skillCategories.business
          actions:
            - what: hide
              when: ~.selectedCategory
              isNot: "business"
        - type: CheckBoxField
          dataLocation: ~.creativeSkills
          dynamicOptions: ~.skillCategories.creative
          actions:
            - what: hide
              when: ~.selectedCategory
              isNot: "creative"
      data:
        selectedCategory: ""
        techSkills: []
        businessSkills: []
        creativeSkills: []
        skillCategories:
          technology:
            - label: "JavaScript"
              value: "javascript"
            - label: "Python"
              value: "python"
            - label: "React"
              value: "react"
            - label: "Node.js"
              value: "nodejs"
          business:
            - label: "Project Management"
              value: "pm"
            - label: "Marketing"
              value: "marketing"
            - label: "Sales"
              value: "sales"
            - label: "Finance"
              value: "finance"
          creative:
            - label: "Graphic Design"
              value: "design"
            - label: "Photography"
              value: "photo"
            - label: "Writing"
              value: "writing"
            - label: "Video Editing"
              value: "video"

  - type: RjBuildDescriber
    title: "Option Attributes"
    description: "CheckBoxField with custom attributes on options"
    toDescribe:
      renderView:
        - type: CheckBoxField
          dataLocation: ~.notifications
          options:
            - label: "Email notifications"
              value: "email"
              attributes:
                style:
                  color: "blue"
            - label: "SMS notifications (premium feature)"
              value: "sms"
              attributes:
                disabled: true
                title: "This feature requires a premium subscription"
            - label: "Push notifications"
              value: "push"
              attributes:
                style:
                  fontWeight: "bold"
        - type: div
          attributes:
            style:
              marginTop: "20px"
              padding: "10px"
              backgroundColor: "#f8f9fa"
              borderRadius: "5px"
          content:
            - type: strong
              content: "Selected Notifications:"
            - type: div
              content:
                - "Current: "
                - ~.notifications
            - type: div
              content: "Note: SMS is disabled (premium feature)"
              attributes:
                style:
                  fontSize: "12px"
                  color: "#666"
      data:
        notifications: []

  - type: Markdown
    content: |
      ## Limitations

      ### Value Types
      - **Numeric values**: May cause issues due to string conversion in HTML input elements
      - **Complex objects**: Cannot be used as option values in array mode
      - **Recommendation**: Use string values for most cases. Numeric and complex value type support may be improved in future versions.

      ### General Limitations
      - Option labels support template evaluation but with limited View component rendering
      - No support for indeterminate checkbox state
      - No built-in option grouping or hierarchical structure
      - Array mode may not preserve object key order in older JavaScript engines
      - No built-in validation for minimum/maximum selections
      - Limited styling options compared to custom checkbox implementations

      ## Value Type Handling

      The component handles special string values in radio mode:
      - Empty string `""` becomes `undefined`
      - String `"true"` becomes boolean `true`
      - String `"false"` becomes boolean `false`
      - String `"null"` becomes `null`
      - Other strings remain as strings

templates: {}
data: {}