{
  "name": "Toggle",
  "source": "src/components/Toggle.tsx",
  "propsType": "ToggleProps",
  "description": "Toggle is a checkbox with `role=\"switch\"`.\n\nNot a button with aria-pressed: a switch is a form value, and the checkbox\ngives form association and `:checked` for free. `role=\"switch\"` changes only\nhow it is announced — \"on/off\" rather than \"checked/unchecked\" — which is\nwhat Figma's On/Off states describe.\n\nThe visual difference from Checkbox is entirely in CSS; this component and\nCheckbox are near-identical by design rather than by accident, and are kept\napart because Figma models them as separate components with separate size\nramps.",
  "import": "import { Toggle } from 'ionbase-ui';",
  "status": "stable",
  "summary": "A switch — a checkbox with role=\"switch\", announced as on/off.",
  "useWhen": [
    "the change takes effect immediately: a setting, a feature flag, a preference"
  ],
  "useInstead": [
    {
      "when": "the value is collected and submitted with a form",
      "use": "Checkbox",
      "why": "a switch reads as taking effect now; a checkbox reads as a value being gathered"
    },
    {
      "when": "there are more than two states",
      "use": "RadioGroup"
    }
  ],
  "variants": {
    "size": {
      "sm": {
        "use": "dense settings rows and table filters"
      },
      "md": {
        "use": "the default"
      },
      "lg": {
        "use": "touch targets and prominent single settings"
      }
    },
    "intent": {
      "brand": {
        "use": "the default"
      },
      "neutral": {
        "use": "a setting with no positive or negative reading — display and layout preferences"
      },
      "danger": {
        "use": "turning on something destructive or hard to undo"
      }
    }
  },
  "slots": {
    "children": {
      "accepts": "text",
      "note": "the visible label; omit for a bare switch and supply `aria-label`"
    }
  },
  "a11y": {
    "role": "switch",
    "guarantees": [
      "a real <input type=\"checkbox\"> underneath, so form association, label clicking and `:checked` come from the platform",
      "`role=\"switch\"` changes only the announcement — \"on/off\" rather than \"checked/unchecked\""
    ],
    "requires": [
      "`children`, or `aria-label` when there is no visible label"
    ]
  },
  "antiPatterns": [
    {
      "dont": "a Toggle with a Save button beside it",
      "why": "a switch says the change is already applied; if it needs saving it is a Checkbox"
    },
    {
      "dont": "labelling a Toggle \"Enable dark mode?\" as a question",
      "why": "a switch label names the thing being switched, not a question about it"
    },
    {
      "dont": "a button with `aria-pressed` for a setting",
      "why": "a switch is a form value; the checkbox gives form association and `:checked` for free"
    },
    {
      "dont": "<Toggle isSelected={on} onChange={(isSelected) => setOn(isSelected)} />",
      "do": "<Toggle isSelected={on} onSelectionChange={setOn} />",
      "why": "as Checkbox: `isSelected` pairs with `onSelectionChange` and `checked` pairs with `onChange(event)`. Toggle extends the input element, so `onChange` keeps the DOM signature it has always had."
    }
  ],
  "deprecated": [
    {
      "prop": "disabled",
      "replacement": "isDisabled"
    }
  ],
  "stylesheet": "src/styles/toggle.css",
  "tokens": [
    "--border-disabled",
    "--border-focus",
    "--border-strong",
    "--border-width-default",
    "--border-width-thick",
    "--font-family-sans",
    "--ion-duration-base",
    "--ion-ease-in-out",
    "--ion-ease-out",
    "--ion-shadow-raised-flush-lg",
    "--ion-shadow-raised-flush-sm",
    "--ion-shadow-raised-flush-xs",
    "--ion-shadow-shadow-xs",
    "--ion-toggle-font-size",
    "--ion-toggle-gap",
    "--ion-toggle-inset",
    "--ion-toggle-line-height",
    "--ion-toggle-on",
    "--ion-toggle-raised",
    "--ion-toggle-thumb",
    "--ion-toggle-track-h",
    "--ion-toggle-track-w",
    "--radius-full",
    "--spacing-12",
    "--spacing-16",
    "--spacing-2",
    "--spacing-20",
    "--spacing-24",
    "--spacing-8",
    "--surface-default",
    "--surface-disabled",
    "--surface-error",
    "--surface-inverse",
    "--surface-muted",
    "--surface-primary",
    "--text-disabled",
    "--text-secondary",
    "--type-body",
    "--type-body-line-height",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "size": {
      "type": "ToggleSize | undefined",
      "required": false,
      "origin": "own",
      "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
      "values": [
        "sm",
        "md",
        "lg"
      ],
      "default": "md"
    },
    "intent": {
      "type": "ToggleIntent | undefined",
      "required": false,
      "origin": "own",
      "description": "Matches the Figma `Color` variant: Brand, Neutral, Danger.",
      "values": [
        "neutral",
        "danger",
        "brand"
      ],
      "default": "brand"
    },
    "isDisabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Whether the toggle is disabled."
    },
    "disabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "tags": {
        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
      }
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own"
    },
    "isSelected": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "React Aria's name for `checked`. Wins when both are passed."
    },
    "onSelectionChange": {
      "type": "((isSelected: boolean) => void) | undefined",
      "required": false,
      "origin": "own",
      "description": "Receives the new selection state rather than the change event."
    }
  },
  "propCounts": {
    "own": 7,
    "aria": 0,
    "dom": 304,
    "other": 0
  }
}