{
  "tag": "ed-checkbox",
  "kind": "component",
  "summary": "Checkboxes allow the user to toggle an option on or off.",
  "status": "experimental",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/checkbox/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/checkbox/usage/",
  "playwright": "getByTestId('…').getByRole('checkbox')",
  "dependencies": [
    "ed-icon"
  ],
  "use": [
    "Opting in or out of a single option — a newsletter subscription, terms acceptance, or a feature toggle in a settings form",
    "Selecting any number of options from a group, including none or all — preferences, filter categories, multi-select configuration",
    "A choice that must be confirmed with a save or submit step before it takes effect",
    "Bulk selection in a table, where each row carries a checkbox that stages a batch action"
  ],
  "notFor": [
    {
      "when": "Exactly one option that must be chosen from a mutually exclusive group",
      "instead": "[Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)"
    },
    {
      "when": "A setting that takes effect immediately, without a save step",
      "instead": "[Switch](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/switch)"
    },
    {
      "when": "Only two named states where neither is obviously \"off\" (e.g., \"Monthly\" vs. \"Annual\")",
      "instead": "[Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)"
    }
  ],
  "rules": [
    {
      "id": "checkbox/positive-label",
      "rule": "Write every label in positive language that describes what the checked state means. Never \"Do not…\", \"Disable…\" or \"Deactivate…\".",
      "why": "Double-negative labels are a confirmed source of user errors in B2B forms. In our products, a misread label can activate or suppress an automated payroll run, notification, or data export without the user realizing.",
      "check": "warning"
    },
    {
      "id": "checkbox/group-label-and-stacking",
      "rule": "Give every group of checkboxes a group label and stack the checkboxes vertically, never horizontally — both are rules of [Checkbox Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/checkbox-group): `checkbox-group/label-the-set` and `checkbox-group/stack-vertically`.",
      "check": "error"
    },
    {
      "id": "checkbox/indeterminate-for-partial",
      "rule": "Use `indeterminate` for a partial group selection — never substitute a checked state.",
      "check": "warning"
    },
    {
      "id": "checkbox/required",
      "rule": "Set `required` on a mandatory checkbox, such as terms acceptance, and explain the required-marking convention once per form. Don't add your own indicator — the label picks it up automatically."
    },
    {
      "id": "checkbox/error-beside-control",
      "rule": "Place error messages directly adjacent to the affected checkbox or group. Don't add your own beside a checkbox — it shows its message at the control.",
      "check": "warning"
    },
    {
      "id": "checkbox/error-timing",
      "rule": "Never show a validation error on load or on first focus. Don't add your own timing — the checkbox shows errors only after the user has interacted with it, or on submit.",
      "check": "error"
    },
    {
      "id": "checkbox/no-pre-checked-consent",
      "rule": "Never pre-check a marketing opt-in, a legal agreement, or any financially consequential setting.",
      "check": "error"
    },
    {
      "id": "checkbox/ai-suggested",
      "rule": "Use the AI-suggested state to flag a value the system pre-filled, so users can tell it apart from their own entries."
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "title",
        "property": "title",
        "type": "string",
        "default": "''"
      },
      {
        "name": "aria-label",
        "property": "ariaLabel",
        "type": "null | string",
        "default": "null",
        "description": "The checkbox's accessible name for when no visible label is slotted (e.g. table selection\ncells). Mirrored onto the internal input, where the checkbox role lives — an aria-label\nleft on the host alone would sit on a role-less element and be ignored by assistive tech."
      },
      {
        "name": "value",
        "property": "value",
        "type": "string",
        "description": "Removing the attribute has to be told apart from assigning `null`, and Lit hands the setter\n`null` for both. The converter marks the attribute path with a sentinel, so removing it restores\nthe `'on'` default the way a native checkbox does, while the property path keeps its own rule."
      },
      {
        "name": "readonly",
        "property": "readonly",
        "type": "boolean",
        "default": "false",
        "description": "Makes the checkbox readonly."
      },
      {
        "name": "indeterminate",
        "property": "indeterminate",
        "type": "boolean",
        "default": "false",
        "description": "Draws the checkbox in an indeterminate state. This is usually applied to checkboxes that represents a \"select\nall/none\" behavior when associated checkboxes have a mix of checked and unchecked states."
      },
      {
        "name": "alternative",
        "property": "alternative",
        "type": "boolean",
        "default": "false",
        "description": "Enables alternative styling"
      },
      {
        "name": "checked",
        "property": "defaultChecked",
        "type": "boolean",
        "description": "The default value of the form control. Primarily used for resetting the form control."
      },
      {
        "name": "required",
        "property": "required",
        "type": "boolean",
        "default": "false",
        "description": "Makes the checkbox a required field."
      },
      {
        "name": "error",
        "property": "error",
        "type": "null | string",
        "default": "null",
        "description": "Draws an error-style input with danger colored border and icon. Set to an empty string (or use the bare attribute `<ed-input error>`) to render error styling without a visible message; submission is still blocked with a localized fallback validation message. Set to a non-empty string to additionally display that message in the message area, above the hint, and use it as the validation message. Set to `null` (the default) or remove the attribute to clear the error."
      },
      {
        "name": "warning",
        "property": "warning",
        "type": "null | string",
        "default": "null",
        "description": "Draws a warning-style input with warning colored border and icon. Set to an empty string (or use the bare attribute `<ed-input warning>`) to render warning styling without a visible message. Set to a non-empty string to additionally display that message in the message area, above the hint. Warnings do not block form submission. Set to `null` (the default) or remove the attribute to clear the warning."
      },
      {
        "name": "ai",
        "property": "ai",
        "type": "boolean",
        "default": "false",
        "description": "Draws an ai-style input with AI colored border and icon. Suppressed visually once\n`hasInteracted` flips, but the property and attribute are preserved so the styling\nreturns after `formResetCallback` clears `hasInteracted`."
      },
      {
        "name": "hint",
        "property": "hint",
        "type": "string",
        "default": "''",
        "description": "The form control's hint text. If you need to display HTML, use the `hint` slot instead."
      },
      {
        "name": "name",
        "property": "name",
        "type": "null | string",
        "default": "null",
        "description": "The name of the input, submitted as a name/value pair with form data."
      },
      {
        "name": "disabled",
        "property": "disabled",
        "type": "boolean",
        "description": "Disables the form control. HTML treats a control as disabled when either its own `disabled` is\nset or an ancestor `<fieldset>` is disabled, so reading this reports the combined state while\nwriting it sets only this element's own. Keeping the two apart is what lets a fieldset be\nre-enabled without clearing a disabled state the consumer set in the meantime."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [
      {
        "name": "checked",
        "description": "Draws the checkbox in a checked state."
      },
      {
        "name": "form",
        "type": "HTMLFormElement | null",
        "description": "By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work."
      },
      {
        "name": "validationTarget",
        "type": "undefined | HTMLElement",
        "description": "Override this to change where constraint validation popups are anchored."
      }
    ],
    "methods": [
      {
        "name": "formStateRestoreCallback",
        "parameters": [
          {
            "name": "state",
            "type": "string | File | FormData | null"
          },
          {
            "name": "reason",
            "type": "'autocomplete' | 'restore'"
          }
        ],
        "description": "The restorable state is the checkedness, because that is what the user entered — `value` comes\nback from the markup on its own, and the base class would otherwise write the restored state\nthere and leave the checkedness untouched. A native checkbox restores exactly the checkedness."
      },
      {
        "name": "click",
        "description": "Simulates a click on the checkbox."
      },
      {
        "name": "focus",
        "parameters": [
          {
            "name": "options",
            "type": "FocusOptions",
            "optional": true
          }
        ],
        "description": "Sets focus on the checkbox."
      },
      {
        "name": "blur",
        "description": "Removes focus from the checkbox."
      },
      {
        "name": "setValue",
        "parameters": [
          {
            "name": "args",
            "type": "Parameters<EdFormAssociatedElement['setValue']>"
          }
        ],
        "description": "A checkbox submits its value only while it is checked, so the guard belongs where the value is\nwritten rather than at each caller. The base class re-runs `setValue` whenever `disabled`\nchanges — right for a text field, whose value stands on its own — and a checkbox enabled while\nunchecked would otherwise put its value into the form with nothing behind it.\n\nShaped after `ed-radio-group`, which guards the same way: through `super` rather than\n`internals.setFormValue`, so anything the base adds to that seam still applies. The restore\nstate is decided here rather than taken from the caller — see below."
      },
      {
        "name": "setCustomValidity",
        "parameters": [
          {
            "name": "message",
            "type": "string"
          }
        ],
        "description": "Do not use this when creating a \"Validator\". This is intended for end users of components.\nWe track manually defined custom errors so we don't clear them on accident in our validators."
      },
      {
        "name": "resetValidity",
        "description": "Reset validity is a way of removing manual custom errors and native validation."
      }
    ],
    "events": [
      {
        "name": "change",
        "react": "onChange",
        "type": "Event",
        "description": "Emitted when the checked state changes."
      },
      {
        "name": "blur",
        "react": "onBlur",
        "description": "Emitted when the checkbox loses focus."
      },
      {
        "name": "focus",
        "react": "onFocus",
        "description": "Emitted when the checkbox gains focus."
      },
      {
        "name": "input",
        "react": "onInput",
        "description": "Emitted when the checkbox receives input."
      },
      {
        "name": "ed-invalid",
        "react": "onEdInvalid",
        "description": "Emitted when the form control has been checked for validity and its constraints aren't satisfied."
      }
    ],
    "slots": [
      {
        "name": "",
        "description": "The checkbox's label."
      },
      {
        "name": "hint",
        "description": "Text that describes how to use the checkbox. Alternatively, you can use the `hint` attribute."
      }
    ],
    "cssProperties": [
      {
        "name": "--ed-checkbox-checked-icon-color",
        "description": "The fill of the control box when checked or indeterminate, and its border color while focused. The glyph is drawn in the form control background color — except with `alternative`, where this property colors the glyph itself."
      },
      {
        "name": "--ed-checkbox-checked-icon-size",
        "description": "The size of the visible control box, and the host's line height with it. The box around it follows --ed-form-control-toggle-size, so raising this alone can push the box past the label."
      }
    ],
    "parts": [
      {
        "name": "base",
        "description": "The component's base wrapper."
      },
      {
        "name": "control",
        "description": "The square container that wraps the checkbox's checked state."
      },
      {
        "name": "icon",
        "description": "The icon element inside the control box, carrying the box fill and the glyph."
      },
      {
        "name": "checked-icon",
        "description": "The checked icon, a `<ed-icon>` element."
      },
      {
        "name": "indeterminate-icon",
        "description": "The indeterminate icon, a `<ed-icon>` element."
      },
      {
        "name": "label",
        "description": "The container that wraps the checkbox's label."
      },
      {
        "name": "message",
        "description": "The state message: an error, a warning, or the AI note."
      },
      {
        "name": "hint",
        "description": "The hint's wrapper."
      }
    ],
    "states": [
      {
        "name": "checked",
        "description": "Applied when the checkbox is checked."
      },
      {
        "name": "disabled",
        "description": "Applied when the checkbox is disabled."
      },
      {
        "name": "indeterminate",
        "description": "Applied when the checkbox is in an indeterminate state."
      },
      {
        "name": "warning",
        "description": "Applied when the checkbox carries the warning hint state."
      },
      {
        "name": "ai",
        "description": "Applied when the checkbox carries the AI hint state."
      },
      {
        "name": "error",
        "description": "Applied when the checkbox carries the error hint state."
      },
      {
        "name": "required",
        "description": "The control is required."
      },
      {
        "name": "optional",
        "description": "The control is not required."
      },
      {
        "name": "invalid",
        "description": "The value fails constraint validation, whether or not the user has touched the control yet."
      },
      {
        "name": "valid",
        "description": "The value passes constraint validation."
      },
      {
        "name": "user-invalid",
        "description": "Invalid, and the user has interacted with the control. This is the one to style for an error: it behaves like the platform's `:user-invalid`, so an untouched field is not marked wrong before the user has had a chance to fill it in."
      },
      {
        "name": "user-valid",
        "description": "Valid, and the user has interacted with the control."
      },
      {
        "name": "dirty",
        "description": "The user has interacted with the control."
      }
    ]
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/checkbox/checkbox.js';",
  "react": {
    "component": "EdCheckbox",
    "import": "import EdCheckbox from '@eurodata/eurodata-ui/dist/react/checkbox/index.js';"
  }
}