{"name":"switch","title":"Switch","description":"A control that allows the user to toggle between checked and not checked.","installCommand":"bunx marko-ui add switch -y","usageTags":"<Switch>","importSnippet":"import Switch from \"@/components/ui/switch/switch.marko\";","usageSnippet":"<let/airplaneMode=false/>\n\n<Switch checked:=airplaneMode/>","tags":["Switch"],"parts":[],"props":[{"name":"checked","type":"boolean | undefined","required":false,"description":"The controlled checked state of the switch"},{"name":"defaultChecked","type":"boolean | undefined","required":false,"description":"The initial checked state of the switch when rendered.\nUse when you don't need to control the checked state of the switch."},{"name":"dir","type":"'ltr' | 'rtl' | undefined","required":false,"default":"ltr","description":"The document's text/writing direction."},{"name":"disabled","type":"boolean | undefined","required":false,"description":"Whether the switch is disabled."},{"name":"form","type":"string | undefined","required":false,"description":"The id of the form that the switch belongs to"},{"name":"getRootNode","type":"(() => ShadowRoot | Document | Node) | undefined","required":false,"description":"A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron."},{"name":"ids","type":"ElementIds | undefined","required":false,"description":"The ids of the elements in the switch. Useful for composition."},{"name":"invalid","type":"boolean | undefined","required":false,"description":"If `true`, the switch is marked as invalid."},{"name":"label","type":"string | undefined","required":false,"description":"Specifies the localized strings that identifies the accessibility elements and their states"},{"name":"name","type":"string | undefined","required":false,"description":"The name of the input field in a switch\n(Useful for form submission)."},{"name":"readOnly","type":"boolean | undefined","required":false,"description":"Whether the switch is read-only"},{"name":"required","type":"boolean | undefined","required":false,"description":"If `true`, the switch input is marked as required,"},{"name":"size","type":"'default' | 'sm'","required":false,"description":"Control size. Upstream (shadcn) styling API; the zag switch machine has\nno `size` prop, so this is purely presentational — forwarded as\n`data-size` on the control, not to the machine."},{"name":"value","type":"string | number | undefined","required":false,"default":"on","description":"The value of switch input. Useful for form submission."}],"events":[{"name":"checkedChange","arg":"boolean"},{"name":"onCheckedChange","arg":"CheckedChangeDetails","description":"Function to call when the switch is clicked."}],"keyboard":[{"keys":"Space","description":"Toggles the switch between checked and unchecked."},{"keys":"Tab","description":"Moves focus to the next focusable element; skips the switch entirely when `disabled`."}],"accessibilityNotes":["Renders a native hidden `<input type=\"checkbox\">` under a styled root `<label>`, so it participates in native form submission and inherits the platform checkbox's semantics.","Always give the switch an accessible name: either pass label text as its own `content` body (its root element is already a `<label>`) or set `aria-label`/`aria-labelledby` directly — never wrap a `Switch` in a second `<label>` or external `FieldLabel`, since that nests two label elements around the same control.","Pass the `invalid` prop (a real `@zag-js/switch` machine prop) to set `aria-invalid`/`data-invalid` on the control for a failed-validation state; pair it with `invalid` on a wrapping `Field` for matching label/description styling.","Set `disabled` to remove the control from the tab order and block pointer input.","Pass `dir=\"rtl\"` to mirror the control and thumb travel direction for right-to-left languages; it is a real machine prop forwarded to every part (root, control, thumb, hidden input), not just a CSS toggle."],"examples":[{"id":"switch-demo","title":"Basic","source":"import Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<Switch id=\"airplane-mode\">Airplane Mode</Switch>","description":"A switch paired with a label via the shared id."},{"id":"switch-description","title":"Description","source":"import Field from \"@marko-ui/shadcn/ui/field/field.marko\";\nimport FieldContent from \"@marko-ui/shadcn/ui/field/field-content.marko\";\nimport FieldDescription from \"@marko-ui/shadcn/ui/field/field-description.marko\";\nimport FieldLabel from \"@marko-ui/shadcn/ui/field/field-label.marko\";\nimport Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<div class=\"w-full max-w-sm\">\n  <Field orientation=\"horizontal\">\n    <FieldContent>\n      <FieldLabel for=\"switch-focus-mode\">Share across devices</FieldLabel>\n      <FieldDescription>\n        Focus is shared across devices, and turns off when you leave the app.\n      </FieldDescription>\n    </FieldContent>\n    <Switch id=\"switch-focus-mode\" ids={ hiddenInput: \"switch-focus-mode\" }/>\n  </Field>\n</div>","description":"Pair a switch with a `Field`, `FieldLabel`, and `FieldDescription` for a labeled row with helper text."},{"id":"switch-choice-card","title":"Choice Card","source":"import FieldGroup from \"@marko-ui/shadcn/ui/field/field-group.marko\";\nimport Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<div class=\"w-full max-w-sm\">\n  <FieldGroup>\n    <div class=\"has-[[data-slot=switch-label][data-state=checked]]:border-primary/30 has-[[data-slot=switch-label][data-state=checked]]:bg-primary/5 dark:has-[[data-slot=switch-label][data-state=checked]]:border-primary/20 dark:has-[[data-slot=switch-label][data-state=checked]]:bg-primary/10 flex w-full items-center justify-between gap-2 rounded-lg border p-2.5\">\n      <label for=\"switch-share\" class=\"flex flex-1 cursor-pointer flex-col gap-0.5 text-left leading-snug\">\n        <span class=\"text-sm leading-none font-medium\">Share across devices</span>\n        <span class=\"text-muted-foreground text-sm font-normal\">\n          Focus is shared across devices, and turns off when you leave the app.\n        </span>\n      </label>\n      <Switch id=\"switch-share\" ids={ hiddenInput: \"switch-share\" }/>\n    </div>\n    <div class=\"has-[[data-slot=switch-label][data-state=checked]]:border-primary/30 has-[[data-slot=switch-label][data-state=checked]]:bg-primary/5 dark:has-[[data-slot=switch-label][data-state=checked]]:border-primary/20 dark:has-[[data-slot=switch-label][data-state=checked]]:bg-primary/10 flex w-full items-center justify-between gap-2 rounded-lg border p-2.5\">\n      <label for=\"switch-notifications\" class=\"flex flex-1 cursor-pointer flex-col gap-0.5 text-left leading-snug\">\n        <span class=\"text-sm leading-none font-medium\">Enable notifications</span>\n        <span class=\"text-muted-foreground text-sm font-normal\">\n          Receive notifications when focus mode is enabled or disabled.\n        </span>\n      </label>\n      <Switch id=\"switch-notifications\" ids={ hiddenInput: \"switch-notifications\" } defaultChecked/>\n    </div>\n  </FieldGroup>\n</div>","description":"A card is a plain wrapping `<div>` with the title/description and the Switch side by side inside it, labelled through `id`/`for`. Card classes passed to Switch's own `class` land on the small pill, not on its root label, so style the wrapper instead."},{"id":"switch-disabled","title":"Disabled","source":"import Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<div class=\"flex items-center gap-4\">\n  <Switch disabled aria-label=\"Disabled switch\"/>\n  <Switch checked disabled aria-label=\"Disabled checked switch\"/>\n</div>","description":"A disabled switch is skipped by the tab order and ignores pointer input."},{"id":"switch-checked","title":"Checked","source":"import Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<Switch checked aria-label=\"Notifications\"/>","description":"Pass `checked` for a controlled switch, or `defaultChecked` to set only the initial state."},{"id":"switch-controlled","title":"Controlled","source":"import Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<let/checked=true/>\n\n<div class=\"flex items-center gap-4\">\n  <Switch\n    aria-label=\"Notifications\"\n    checked=checked\n    checkedChange=(next) => { checked = next; }\n  />\n  <span class=\"text-sm text-muted-foreground\">checked: ${String(checked)}</span>\n</div>","description":"Zag machines are controlled: a `checked` prop without a change handler never moves. Pair it with `checkedChange`, or use Marko's bind shorthand `checked:=state`.","essential":true},{"id":"switch-invalid","title":"Invalid","source":"import Field from \"@marko-ui/shadcn/ui/field/field.marko\";\nimport FieldContent from \"@marko-ui/shadcn/ui/field/field-content.marko\";\nimport FieldDescription from \"@marko-ui/shadcn/ui/field/field-description.marko\";\nimport FieldLabel from \"@marko-ui/shadcn/ui/field/field-label.marko\";\nimport Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<div class=\"w-full max-w-sm\">\n  <Field orientation=\"horizontal\" invalid>\n    <FieldContent>\n      <FieldLabel for=\"switch-terms\">Accept terms and conditions</FieldLabel>\n      <FieldDescription>You must accept the terms and conditions to continue.</FieldDescription>\n    </FieldContent>\n    <Switch id=\"switch-terms\" ids={ hiddenInput: \"switch-terms\" } invalid/>\n  </Field>\n</div>","description":"Add the `invalid` prop to the `Switch` to mark it invalid; add `invalid` to a wrapping `Field` for matching label/description styling."},{"id":"switch-sizes","title":"Size","source":"import Field from \"@marko-ui/shadcn/ui/field/field.marko\";\nimport FieldGroup from \"@marko-ui/shadcn/ui/field/field-group.marko\";\nimport FieldLabel from \"@marko-ui/shadcn/ui/field/field-label.marko\";\nimport Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<div class=\"w-full max-w-40\">\n  <FieldGroup>\n    <Field orientation=\"horizontal\">\n      <Switch id=\"switch-size-sm\" ids={ hiddenInput: \"switch-size-sm\" } size=\"sm\"/>\n      <FieldLabel for=\"switch-size-sm\">Small</FieldLabel>\n    </Field>\n    <Field orientation=\"horizontal\">\n      <Switch id=\"switch-size-default\" ids={ hiddenInput: \"switch-size-default\" } size=\"default\"/>\n      <FieldLabel for=\"switch-size-default\">Default</FieldLabel>\n    </Field>\n  </FieldGroup>\n</div>","description":"Use the `size` prop (`\"sm\"` or `\"default\"`) to change the size of the switch."},{"id":"switch-rtl","title":"RTL","source":"import Field from \"@marko-ui/shadcn/ui/field/field.marko\";\nimport FieldContent from \"@marko-ui/shadcn/ui/field/field-content.marko\";\nimport FieldDescription from \"@marko-ui/shadcn/ui/field/field-description.marko\";\nimport FieldLabel from \"@marko-ui/shadcn/ui/field/field-label.marko\";\nimport Switch from \"@marko-ui/shadcn/ui/switch/switch.marko\";\n\n<div dir=\"rtl\" class=\"w-full max-w-sm\">\n  <Field orientation=\"horizontal\">\n    <FieldContent>\n      <FieldLabel for=\"switch-focus-mode-rtl\" dir=\"rtl\">المشاركة عبر الأجهزة</FieldLabel>\n      <FieldDescription dir=\"rtl\">\n        يتم مشاركة التركيز عبر الأجهزة، ويتم إيقاف تشغيله عند مغادرة التطبيق.\n      </FieldDescription>\n    </FieldContent>\n    <Switch id=\"switch-focus-mode-rtl\" ids={ hiddenInput: \"switch-focus-mode-rtl\" } dir=\"rtl\"/>\n  </Field>\n</div>","description":"Pass `dir=\"rtl\"` to mirror the switch and its thumb travel direction for right-to-left languages."}],"importInstallCommand":"bun add @marko-ui/shadcn marko-zag","body":{"description":"Label text rendered after the control (Zag's `label` part), which also\nbecomes the accessible name of the hidden checkbox. Without it, pass\n`aria-label` instead — a switch must have a name."},"nativeAttributes":"input","composition":"`Switch` is a single-file, single-part component: its root element is already a `<label>` (Zag's root/label part), wrapping a styled control `<span>` (with the thumb inside) and the hidden native `<input type=\"checkbox\">`. Pass label text as the switch's `content` body to render it inside that root label — the switch's own `aria-labelledby` then targets it automatically. There is no separate `SwitchLabel` or `SwitchThumb` part to import; visual pieces are addressed with CSS (`mu-switch`, `mu-switch-thumb`) or `data-slot` selectors (`switch`, `switch-thumb`, `switch-text`), not composition."}