{
  "_copyright": "Copyright (c) 2026, Salesforce, Inc., All rights reserved. For full license text, see the LICENSE.txt file",
  "$schema": "https://slds.lightningdesignsystem.com/schemas/uif-foundation.v1.json",
  "apiVersion": "1.0.0",
  "name": "Checkbox",
  "description": "A checkable input that communicates if an option is true, false or indeterminate",
  "structure": {
    "name": "root",
    "restrict": [
      "div",
      "fieldset"
    ],
    "description": "Form element envelope. Use a fieldset when rendering a group of related checkboxes; use a div otherwise.",
    "children": [
      {
        "name": "legend",
        "restrict": [
          "legend"
        ],
        "description": "Group caption. Rendered when the component represents a group of checkboxes (fieldset envelope).",
        "renderWhen": {
          "prop": "kind",
          "eq": "group"
        },
        "children": [
          {
            "name": "legendRequiredIndicator",
            "restrict": [
              "abbr"
            ],
            "description": "Required indicator displayed inside the group legend",
            "renderWhen": "propFilled"
          },
          {
            "name": "legendText",
            "restrict": [
              "span"
            ],
            "description": "Group caption text",
            "slot": {
              "name": "legend"
            }
          }
        ]
      },
      {
        "name": "formLabel",
        "restrict": [
          "label",
          "span"
        ],
        "description": "Top-level form-element label rendered above the checkbox when the checkbox is laid out as a stand-alone form field (label sits outside the checkbox block).",
        "renderWhen": "slotFilled",
        "attributes": {
          "bound": {
            "for": {
              "prop": "inputId"
            }
          }
        },
        "children": [
          {
            "name": "formLabelRequiredIndicator",
            "restrict": [
              "abbr"
            ],
            "description": "Required indicator displayed inside the form label",
            "renderWhen": "propFilled"
          },
          {
            "name": "formLabelText",
            "restrict": [
              "span"
            ],
            "description": "Form label text",
            "slot": {
              "name": "label"
            }
          }
        ]
      },
      {
        "name": "helpIcon",
        "restrict": [
          "div"
        ],
        "description": "Container for the help-icon button (info tooltip) shown next to the form-element label",
        "renderWhen": "slotFilled",
        "children": [
          {
            "name": "helpIconButton",
            "restrict": [
              "button"
            ],
            "description": "Icon button that toggles the help tooltip",
            "attributes": {
              "static": {
                "type": "button"
              },
              "bound": {
                "aria-describedby": {
                  "prop": "helpTooltipId"
                }
              }
            },
            "children": [
              {
                "name": "helpIconSvg",
                "description": "Help icon glyph",
                "component": "PrimitiveIcon"
              },
              {
                "name": "helpIconAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually hidden accessible label for the help button"
              }
            ]
          },
          {
            "name": "helpTooltip",
            "restrict": [
              "div"
            ],
            "description": "Tooltip popover anchored to the help-icon button",
            "renderWhen": "slotFilled",
            "attributes": {
              "static": {
                "role": "tooltip"
              },
              "bound": {
                "id": {
                  "prop": "helpTooltipId"
                }
              }
            },
            "children": [
              {
                "name": "helpTooltipBody",
                "restrict": [
                  "div"
                ],
                "description": "Tooltip body content",
                "slot": {
                  "name": "helpText"
                }
              }
            ]
          }
        ]
      },
      {
        "name": "control",
        "restrict": [
          "div"
        ],
        "description": "Form-element control region that hosts one or more checkbox blocks",
        "children": [
          {
            "name": "checkbox",
            "restrict": [
              "div",
              "span"
            ],
            "description": "Initializes checkbox",
            "repeats": true,
            "children": [
              {
                "name": "requiredIndicator",
                "restrict": [
                  "abbr"
                ],
                "description": "Required indicator rendered inside the checkbox block (used when the checkbox is a bare single field without a separate form label)",
                "renderWhen": "propFilled"
              },
              {
                "name": "input",
                "restrict": [
                  "input"
                ],
                "description": "Native checkbox input",
                "attributes": {
                  "static": {
                    "type": "checkbox"
                  },
                  "bound": {
                    "id": {
                      "prop": "inputId",
                      "required": true
                    },
                    "name": {
                      "prop": "name"
                    },
                    "value": {
                      "prop": "value"
                    },
                    "checked": {
                      "prop": "checked"
                    },
                    "disabled": {
                      "prop": "disabled"
                    },
                    "required": {
                      "prop": "required"
                    },
                    "aria-describedby": {
                      "prop": "ariaDescribedBy"
                    }
                  }
                }
              },
              {
                "name": "label",
                "restrict": [
                  "label"
                ],
                "description": "Container for faux checkbox, text, and slds-form-element__label",
                "renderWhen": "slotFilled",
                "attributes": {
                  "bound": {
                    "for": {
                      "prop": "inputId"
                    }
                  }
                },
                "children": [
                  {
                    "name": "faux",
                    "restrict": [
                      "span"
                    ],
                    "description": "Creates a custom styled checkbox"
                  },
                  {
                    "name": "labelText",
                    "restrict": [
                      "span"
                    ],
                    "description": "Inline label text",
                    "slot": {
                      "name": "default",
                      "required": true
                    }
                  }
                ]
              },
              {
                "name": "standaloneFaux",
                "restrict": [
                  "span"
                ],
                "description": "Creates a custom styled checkbox",
                "renderWhen": {
                  "prop": "layout",
                  "eq": "standalone"
                }
              }
            ]
          },
          {
            "name": "readonlyIcon",
            "restrict": [
              "span"
            ],
            "description": "Read-only display: a check or steps glyph standing in for the input when the form element is in view mode",
            "renderWhen": {
              "prop": "viewMode",
              "eq": "readonly"
            },
            "children": [
              {
                "name": "readonlyIconSvg",
                "description": "Read-only display icon",
                "component": "PrimitiveIcon"
              },
              {
                "name": "readonlyIconAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually hidden accessible label describing the read-only value"
              }
            ]
          }
        ]
      },
      {
        "name": "errorMessage",
        "restrict": [
          "div"
        ],
        "description": "Validation error message associated with the field via aria-describedby",
        "renderWhen": {
          "prop": "hasError",
          "eq": "true"
        },
        "attributes": {
          "bound": {
            "id": {
              "prop": "errorId"
            }
          }
        }
      }
    ]
  },
  "states": [
    {
      "name": "checked",
      "type": "boolean",
      "description": "Whether the checkbox is checked"
    },
    {
      "name": "indeterminate",
      "type": "boolean",
      "aria": "aria-checked",
      "description": "Whether the checkbox is in an indeterminate state"
    },
    {
      "name": "disabled",
      "type": "boolean",
      "description": "Whether the checkbox is disabled"
    },
    {
      "name": "required",
      "type": "boolean",
      "aria": "aria-required",
      "description": "Whether the checkbox (or checkbox group) is required"
    },
    {
      "name": "hasError",
      "type": "boolean",
      "description": "Whether the checkbox has a validation error"
    },
    {
      "name": "readonly",
      "type": "boolean",
      "description": "Whether the form element is rendered in read-only / view mode"
    }
  ],
  "accessibility": {
    "requirements": [
      {
        "id": "label-association",
        "description": "Checkbox must have an associated label via for/id"
      },
      {
        "id": "group-legend",
        "description": "When rendering a group of checkboxes, wrap them in a fieldset and label the group with a legend"
      },
      {
        "id": "error-announcement",
        "description": "Error messages must be associated with the input via aria-describedby"
      },
      {
        "id": "required-indicator",
        "description": "The asterisk indicator is decorative and must be hidden from assistive tech (aria-hidden); communicate required-ness on the input via the required attribute or aria-required"
      },
      {
        "id": "readonly-value",
        "description": "Read-only view of the checkbox value must expose the stored value (True/False) as accessible text"
      }
    ]
  },
  "componentRefs": {
    "PrimitiveIcon": {
      "description": "Bare SVG icon composed directly inside the component. The host node supplies the SVG class (e.g. slds-button__icon, slds-menu__item-icon) via componentProps; PrimitiveIcon contributes the sprite-href binding.",
      "props": {
        "iconName": {
          "type": "string",
          "required": true,
          "description": "Sprite reference for the icon glyph"
        }
      }
    }
  }
}