{
  "tag": "ed-switch",
  "kind": "component",
  "summary": "Switches 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/switch/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/switch/usage/",
  "playwright": "getByTestId('…').getByRole('switch')",
  "dependencies": [
    "ed-icon"
  ],
  "use": [
    "A single on/off setting that takes effect the instant it is toggled — enabling a notification, activating an automated process, switching a display preference",
    "Settings panels and preference screens, outside of any form that has a save or submit step",
    "A user turning a feature on or off, such as email notifications or automatic reminders, and seeing the change apply immediately",
    "A preference that has a clear on and off state, with a hint explaining what turning it on will do"
  ],
  "notFor": [
    {
      "when": "A setting that only applies after a save or submit step",
      "instead": "a [Checkbox](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/checkbox)"
    },
    {
      "when": "Toggling between two named modes — \"Table\"/\"Chart\", \"Gross\"/\"Net\"",
      "instead": "[Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)'s button appearance (segmented control)"
    },
    {
      "when": "Picking exactly one option from a mutually exclusive set",
      "instead": "[Radio Group](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/radio-group)"
    },
    {
      "when": "A setting with more than two meaningful states",
      "instead": "a [Select](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/select)"
    }
  ],
  "rules": [
    {
      "id": "switch/immediate-effect",
      "rule": "Use a switch only when the change takes effect immediately — no save step, and never a confirmation dialog attached to the toggle.",
      "why": "A confirmation breaks the immediate-effect promise the control makes, and a switch inside a form that is only applied after a separate save action falsely implies the setting is already live. In payroll and financial configuration this leads users to believe a setting is active when it has not been saved.",
      "check": "warning"
    },
    {
      "id": "switch/true-binary",
      "rule": "Use it only for a true binary with a clear \"off\" state and a sensible default."
    },
    {
      "id": "switch/label",
      "rule": "Label the switch with a noun or noun phrase that names the setting — \"Notifications\", \"Automatic sending\", \"Logging\" — in positive, direct language that names what it enables. Never an action verb (\"Enable notifications\", \"Turn on logging\"), which belongs on a button, and never a negated label (\"No notifications\", \"No automatic sending\").",
      "check": "warning"
    },
    {
      "id": "switch/default-value",
      "rule": "Set a default that matches the setting's most common or safest value."
    },
    {
      "id": "switch/hint-for-consequence",
      "rule": "Add a hint when the consequence of turning the setting on or off is not self-evident."
    },
    {
      "id": "switch/readonly-not-disabled",
      "rule": "Use read-only for a setting the user can never change, and disabled only when it could become editable under some condition."
    },
    {
      "id": "switch/ai-suggested",
      "rule": "Use the AI-suggested state to flag a setting the system pre-set, so users can tell it apart from their own choices."
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "title",
        "property": "title",
        "type": "string",
        "default": "''"
      },
      {
        "name": "aria-label",
        "property": "ariaLabel",
        "type": "null | string",
        "default": "null",
        "description": "The switch's accessible name for when no visible label is slotted. Mirrored onto the internal\ninput, where the switch role lives — an aria-label left on the host alone would sit on a\nrole-less element and be ignored by assistive tech."
      },
      {
        "name": "name",
        "property": "name",
        "type": "null | string",
        "default": "null",
        "description": "The name of the switch, submitted as a name/value pair with form data."
      },
      {
        "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 switch readonly."
      },
      {
        "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 switch a required field."
      },
      {
        "name": "with-hint",
        "property": "withHint",
        "type": "boolean",
        "default": "false",
        "description": "Only required for SSR. Set to `true` if you're slotting in a `hint` element so the server-rendered markup includes the hint before the component hydrates on the client."
      },
      {
        "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": "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 switch 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 switch."
      },
      {
        "name": "focus",
        "parameters": [
          {
            "name": "options",
            "type": "FocusOptions",
            "optional": true
          }
        ],
        "description": "Sets focus on the switch."
      },
      {
        "name": "blur",
        "description": "Removes focus from the switch."
      },
      {
        "name": "setValue",
        "parameters": [
          {
            "name": "args",
            "type": "Parameters<EdFormAssociatedElement['setValue']>"
          }
        ],
        "description": "A switch submits its value only while it is on. Through `super` rather than\n`internals.setFormValue`, so anything the base class adds to that seam still applies here —\n`ed-form-associated-element.ts` omits `setFormValue` from its public surface for exactly that\nreason — and passing the state value along untouched, since it is what the browser hands back\non back-navigation. `ed-checkbox` and `ed-radio-group` guard the same way."
      },
      {
        "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 control's checked state changes."
      },
      {
        "name": "input",
        "react": "onInput",
        "type": "InputEvent",
        "description": "Emitted when the control receives input."
      },
      {
        "name": "blur",
        "react": "onBlur",
        "description": "Emitted when the control loses focus."
      },
      {
        "name": "focus",
        "react": "onFocus",
        "description": "Emitted when the control gains focus."
      },
      {
        "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 switch's label."
      },
      {
        "name": "hint",
        "description": "Text that describes how to use the switch. Alternatively, you can use the `hint` attribute."
      }
    ],
    "cssProperties": [
      {
        "name": "--ed-switch-width",
        "description": "The width of the switch."
      },
      {
        "name": "--ed-switch-height",
        "description": "The height of the switch."
      },
      {
        "name": "--ed-switch-thumb-size",
        "description": "The size of the thumb."
      }
    ],
    "parts": [
      {
        "name": "base",
        "description": "The component's base wrapper."
      },
      {
        "name": "control",
        "description": "The control that houses the switch's thumb."
      },
      {
        "name": "thumb",
        "description": "The switch's thumb."
      },
      {
        "name": "label",
        "description": "The switch'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 switch is checked."
      },
      {
        "name": "disabled",
        "description": "Applied when the switch is disabled."
      },
      {
        "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."
      },
      {
        "name": "error",
        "description": "The `error` property is set, or the control is `user-invalid`."
      },
      {
        "name": "warning",
        "description": "The `warning` property is set."
      },
      {
        "name": "ai",
        "description": "The `ai` property is set and the user has not interacted with the control yet."
      }
    ]
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/switch/switch.js';",
  "react": {
    "component": "EdSwitch",
    "import": "import EdSwitch from '@eurodata/eurodata-ui/dist/react/switch/index.js';"
  }
}