{"_id":"@agencecinq/switch","_rev":"5-4eb6316d5ab40b8173125ed115d3c8d0","name":"@agencecinq/switch","dist-tags":{"latest":"3.0.1"},"versions":{"2.0.0":{"name":"@agencecinq/switch","version":"2.0.0","author":{"url":"https://agencecinq.com","name":"Jérémy Levron","email":"jeremy@agencecinq.com"},"license":"MIT","_id":"@agencecinq/switch@2.0.0","maintainers":[{"name":"19h47","email":"jeremylevron@19h47.fr"}],"homepage":"https://github.com/agencecinq/shopify#readme","bugs":{"url":"https://github.com/agencecinq/shopify/issues"},"dist":{"shasum":"1e82b039ec58fe2d92e20a4a9e22c88bf7a54885","tarball":"https://registry.npmjs.org/@agencecinq/switch/-/switch-2.0.0.tgz","fileCount":9,"integrity":"sha512-1Dvj5QRcT+8lDL0v4pftjnIA43Thx/TegibPeVL+g+P0I9D9nBtpTOBMGLuxWSFeTOu9GMXSrOn5iJm2IRzfxg==","signatures":[{"sig":"MEYCIQCSkJJLL5Wk13O1x/snh9y4B7rlnEYcRcs/R6s0gzk/4AIhAJJ0o0uXkA3TCamXk6XAkV9dZywuLM4EzUTcU8MvKlPz","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13843},"main":"./dist/index.js","type":"module","_from":"file:agencecinq-switch-2.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"vite build --watch","build":"vite build"},"_npmUser":{"name":"19h47","email":"jeremylevron@19h47.fr"},"_resolved":"/private/var/folders/vt/kpbgrh4d7k14zvxmcm01bfxh0000gn/T/5699c9a3967d2559fd0541415c8b5f59/agencecinq-switch-2.0.0.tgz","_integrity":"sha512-1Dvj5QRcT+8lDL0v4pftjnIA43Thx/TegibPeVL+g+P0I9D9nBtpTOBMGLuxWSFeTOu9GMXSrOn5iJm2IRzfxg==","repository":{"url":"git+https://github.com/agencecinq/shopify.git","type":"git","directory":"packages/switch"},"_npmVersion":"11.18.0","description":"Accessible, WAI-ARIA switch as a lightweight Web Component.","directories":{},"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.1.4","vite-plugin-dts":"^5.0.3","@agencecinq/utils":"5.0.3"},"peerDependencies":{"@agencecinq/utils":"*"},"_npmOperationalInternal":{"tmp":"tmp/switch_2.0.0_1783576544466_0.27708706086858803","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@agencecinq/switch","version":"2.0.1","author":{"url":"https://agencecinq.com","name":"Jérémy Levron","email":"jeremy@agencecinq.com"},"license":"MIT","_id":"@agencecinq/switch@2.0.1","maintainers":[{"name":"19h47","email":"jeremylevron@19h47.fr"}],"homepage":"https://github.com/agencecinq/shopify#readme","bugs":{"url":"https://github.com/agencecinq/shopify/issues"},"dist":{"shasum":"e4d0739381436a0b4ea882cc3e66cc9f39d74904","tarball":"https://registry.npmjs.org/@agencecinq/switch/-/switch-2.0.1.tgz","fileCount":9,"integrity":"sha512-9Vx/xR3uKkwwysY97yGjWon29BnA83k/HCrwaB6UleKVLOzm7l0msjRQ4BhWaLqsz4sEWfvr6e4s0IFNM0dP5w==","signatures":[{"sig":"MEQCIFrzfwLyWX6IW7CS0R5ClpHqnj6yh5GF1+t5/UMiIhMeAiB+tVrc4Ctjvwr0uisTZgTXVvTwNhsPdrOUVjLVcuMH4w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14245},"main":"./dist/index.js","type":"module","_from":"file:agencecinq-switch-2.0.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"vite build --watch","build":"vite build"},"_npmUser":{"name":"19h47","email":"jeremylevron@19h47.fr"},"_resolved":"/private/var/folders/vt/kpbgrh4d7k14zvxmcm01bfxh0000gn/T/96fdb20a7d9b5477d9dc6890e4dcd22c/agencecinq-switch-2.0.1.tgz","_integrity":"sha512-9Vx/xR3uKkwwysY97yGjWon29BnA83k/HCrwaB6UleKVLOzm7l0msjRQ4BhWaLqsz4sEWfvr6e4s0IFNM0dP5w==","repository":{"url":"git+https://github.com/agencecinq/shopify.git","type":"git","directory":"packages/switch"},"_npmVersion":"11.18.0","description":"Accessible, WAI-ARIA switch as a lightweight Web Component.","directories":{},"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.1.4","vite-plugin-dts":"^5.0.3","@agencecinq/utils":"5.1.0"},"peerDependencies":{"@agencecinq/utils":"*"},"_npmOperationalInternal":{"tmp":"tmp/switch_2.0.1_1784557065525_0.7214213216221046","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"@agencecinq/switch","version":"3.0.0","author":{"url":"https://agencecinq.com","name":"Jérémy Levron","email":"jeremy@agencecinq.com"},"license":"MIT","_id":"@agencecinq/switch@3.0.0","maintainers":[{"name":"19h47","email":"jeremylevron@19h47.fr"}],"homepage":"https://github.com/agencecinq/shopify#readme","bugs":{"url":"https://github.com/agencecinq/shopify/issues"},"dist":{"shasum":"6e6b866abf3df377f260453045ca47a532abb36d","tarball":"https://registry.npmjs.org/@agencecinq/switch/-/switch-3.0.0.tgz","fileCount":9,"integrity":"sha512-F0+xbMWnDLT/TPUYEhIX3eFVZ0Yvt4t6/uFETAb4+779g+KcdZkVVNRudY7/iPIBqS4SHioQAM7UGam//+7ZEw==","signatures":[{"sig":"MEUCIQCGWrICEwS/eX+lrDH/YGuRqYSUg+Wd1CBBUlgFtkzOSwIgMv+9lECnQ2nIzxvrbfGVWZzUvPqrky77eWfCtHEHQOU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13307},"main":"./dist/index.js","type":"module","_from":"file:agencecinq-switch-3.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"vite build --watch","build":"vite build"},"_npmUser":{"name":"19h47","email":"jeremylevron@19h47.fr"},"_resolved":"/private/var/folders/vt/kpbgrh4d7k14zvxmcm01bfxh0000gn/T/ba8625dc3057b445dd876245bd382a66/agencecinq-switch-3.0.0.tgz","_integrity":"sha512-F0+xbMWnDLT/TPUYEhIX3eFVZ0Yvt4t6/uFETAb4+779g+KcdZkVVNRudY7/iPIBqS4SHioQAM7UGam//+7ZEw==","repository":{"url":"git+https://github.com/agencecinq/shopify.git","type":"git","directory":"packages/switch"},"_npmVersion":"11.18.0","description":"Accessible, WAI-ARIA switch as a lightweight Web Component.","directories":{},"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.2.0","vite-plugin-dts":"^5.0.3","@agencecinq/utils":"6.0.0"},"peerDependencies":{"@agencecinq/utils":"*"},"_npmOperationalInternal":{"tmp":"tmp/switch_3.0.0_1785915311321_0.42018504938483625","host":"s3://npm-registry-packages-npm-production"}},"3.0.1":{"name":"@agencecinq/switch","version":"3.0.1","author":{"url":"https://agencecinq.com","name":"Jérémy Levron","email":"jeremy@agencecinq.com"},"license":"MIT","_id":"@agencecinq/switch@3.0.1","maintainers":[{"name":"19h47","email":"jeremylevron@19h47.fr"}],"homepage":"https://github.com/agencecinq/shopify#readme","bugs":{"url":"https://github.com/agencecinq/shopify/issues"},"dist":{"shasum":"a484b6af3e8ffebdeaf3bfbf13eac2a18674d97c","tarball":"https://registry.npmjs.org/@agencecinq/switch/-/switch-3.0.1.tgz","fileCount":9,"integrity":"sha512-pK/9cAghBcFZGdUuabIJrb2tgFpWluXQUF2O1Wrp+gVJKvQz2zwGEuHRrurZzVUBfVo9kyl7wp+RKT8YMMmzyw==","signatures":[{"sig":"MEUCIF1V2n1Dqo8AM+BNRm6rUb65n9NxHbgRrnkowSZMAVM8AiEArF3qdybi2iEx2joFe16pN3+F8MJ5XTQAU1XCnJRTFR0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13208},"main":"./dist/index.js","type":"module","_from":"file:agencecinq-switch-3.0.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"vite build --watch","build":"vite build"},"_npmUser":{"name":"19h47","email":"jeremylevron@19h47.fr"},"_resolved":"/private/var/folders/vt/kpbgrh4d7k14zvxmcm01bfxh0000gn/T/d46fca9ba25b37a23ac37f72d02fc7c3/agencecinq-switch-3.0.1.tgz","_integrity":"sha512-pK/9cAghBcFZGdUuabIJrb2tgFpWluXQUF2O1Wrp+gVJKvQz2zwGEuHRrurZzVUBfVo9kyl7wp+RKT8YMMmzyw==","repository":{"url":"git+https://github.com/agencecinq/shopify.git","type":"git","directory":"packages/switch"},"_npmVersion":"11.18.0","description":"Accessible, WAI-ARIA switch as a lightweight Web Component.","directories":{},"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.2.0","vite-plugin-dts":"^5.0.3","@agencecinq/utils":"6.1.0"},"peerDependencies":{"@agencecinq/utils":"*"},"_npmOperationalInternal":{"tmp":"tmp/switch_3.0.1_1786088893806_0.3140460148443027","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-07-09T05:55:44.361Z","modified":"2026-09-15T13:10:48.532Z","2.0.0":"2026-07-09T05:55:44.617Z","2.0.1":"2026-07-20T14:17:45.642Z","3.0.0":"2026-08-05T07:35:11.551Z","3.0.1":"2026-08-07T07:48:13.970Z"},"bugs":{"url":"https://github.com/agencecinq/shopify/issues"},"author":{"url":"https://agencecinq.com","name":"Jérémy Levron","email":"jeremy@agencecinq.com"},"license":"MIT","homepage":"https://github.com/agencecinq/shopify#readme","repository":{"url":"git+https://github.com/agencecinq/shopify.git","type":"git","directory":"packages/switch"},"description":"Accessible, WAI-ARIA switch as a lightweight Web Component.","maintainers":[{"email":"jeremylevron@19h47.fr","name":"19h47"},{"email":"pauline@agencecinq.com","name":"paulinecinq"}],"readme":"[![](https://img.shields.io/npm/v/@agencecinq/switch)](https://www.npmjs.com/package/@agencecinq/switch)\n[![](https://img.shields.io/npm/dm/@agencecinq/switch)](https://www.npmjs.com/package/@agencecinq/switch)\n\n# @agencecinq/switch\n\n> Accessible, WAI-ARIA switch as a lightweight Web Component.\n\nA switch is an on/off control that represents a binary setting. `<cinq-switch>`\nprovides an accessible, keyboard-navigable interface following the ARIA switch\npattern, reads its state from the markup, syncs an optional hidden checkbox,\nand dispatches events when toggled.\n\nImplementation follows the\n[WAI-ARIA Authoring Practices switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).\nInspired by [`@19h47/switch`](https://github.com/19h47/19h47-switch).\n\n## Installation\n\n```bash\npnpm add @agencecinq/switch\n```\n\n## Usage\n\n### Web Component (`<cinq-switch>`)\n\n```html\n<cinq-switch role=\"switch\" aria-checked=\"false\" tabindex=\"0\">\n  <span class=\"label\">Notifications</span>\n  <span class=\"switch\" aria-hidden=\"true\"><span></span></span>\n  <span class=\"on\" aria-hidden=\"true\">On</span>\n  <span class=\"off\" aria-hidden=\"true\">Off</span>\n  <div hidden>\n    <input type=\"checkbox\" tabindex=\"-1\" aria-hidden=\"true\" />\n  </div>\n</cinq-switch>\n```\n\n```js\nimport \"@agencecinq/switch\";\n```\n\nWhen disabled, use `disabled` or `aria-disabled=\"true\"` and `tabindex=\"-1\"`:\n\n```html\n<cinq-switch role=\"switch\" aria-checked=\"false\" disabled aria-disabled=\"true\" tabindex=\"-1\">\n  <span class=\"label\">Disabled switch</span>\n  <span class=\"switch\" aria-hidden=\"true\"><span></span></span>\n  <div hidden>\n    <input type=\"checkbox\" tabindex=\"-1\" aria-hidden=\"true\" disabled />\n  </div>\n</cinq-switch>\n```\n\nImporting `@agencecinq/switch` registers the Web Component in the\n**Custom Elements Registry** (`customElements.define('cinq-switch', Switch)`).\nThe browser upgrades every existing `<cinq-switch>` in the DOM automatically —\nno manual `init()` call required.\n\n> **HTML is the source of truth.** The component will not auto-set `role`,\n> auto-migrate attributes, or warn about missing labels. Use an a11y linter\n> (axe-core, Lighthouse) to catch invalid markup.\n\n### Required markup\n\n| Attribute / element | Required | Role |\n| ------------------- | -------- | ---- |\n| `<cinq-switch>` | **Yes** | Host element with `role=\"switch\"`. |\n| `role=\"switch\"` | **Yes** | Identifies the control as a switch. |\n| `aria-checked` | **Yes** | Current on/off state (`\"true\"` or `\"false\"`). |\n| `tabindex=\"0\"` | **Yes** | Makes the switch keyboard-focusable (use `-1` when disabled). |\n| Hidden `<input>` | Optional | Form helper only — not the switch. One input in the host. Keep it in a `hidden` container, with `tabindex=\"-1\"` and `aria-hidden=\"true\"`. |\n| `aria-hidden=\"true\"` on On/Off text | Recommended | Decorative state labels must not appear in the accessible name ([APG](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)). |\n\nThe switch **label must not change** when its state changes — update decorative\nOn/Off text only if it is marked `aria-hidden=\"true\"`.\n\n### Switch groups\n\nWhen presenting multiple switches, wrap them in a `<fieldset>` with a `<legend>`,\nor in an element with `role=\"group\"` and `aria-labelledby` pointing to the\ngroup label ([APG](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)).\n\n### Markup variants\n\n| Variant | Markup |\n| ------- | ------ |\n| Visible label | Text inside `<cinq-switch>` |\n| `aria-label` | On the host when no visible label |\n| `aria-labelledby` | References an external visible label |\n| `aria-describedby` | Points to static help text |\n| Minimal | Host + label only — no slider, no checkbox |\n| Pre-checked | `aria-checked=\"true\"` (+ optional `checked` for CSS) |\n| Form helper | Hidden `<input>` in `<div hidden>` |\n| Disabled | `disabled` + `aria-disabled` + `tabindex=\"-1\"`, or `aria-disabled` alone |\n\nSee the [interactive docs](https://agencecinq.github.io/ui/components/switch/) for live examples of each variant.\n\n### API\n\n| Attribute | Required | Description |\n| --------- | -------- | ----------- |\n| `checked` | No | Reflected state on the host — useful for styling the wrapper. |\n| `disabled` | No | Observed — syncs the hidden checkbox and blurs focus when set externally. Pair with `aria-disabled=\"true\"` and `tabindex=\"-1\"` in markup. |\n\n| Method | Description |\n| ------ | ----------- |\n| `init()` | Binds markup + listeners. Call `destroy()` first if already bound. |\n| `activate(emit?)` | Turns the switch on. |\n| `deactivate(emit?)` | Turns the switch off. |\n| `toggle()` | Toggles on/off. |\n| `destroy()` | Detaches listeners. |\n\n### Keyboard support\n\n| Key | Function |\n| --- | -------- |\n| `Tab` | Moves keyboard focus to the switch (`tabindex=\"0\"` in markup). |\n| `Space` | Toggles between on and off when focused. |\n| `Enter` | Toggles between on and off when focused (optional per [APG](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)). |\n\nStyle focus with native pseudo-classes:\n\n```css\ncinq-switch:focus-visible {\n  outline: 2px solid currentColor;\n  outline-offset: 2px;\n}\n```\n\n### Programmatic API\n\n```js\nconst $switch = document.querySelector(\"cinq-switch\");\n\n$switch.activate();\n$switch.deactivate();\n$switch.toggle();\n```\n\n`activate()` and `deactivate()` accept an optional `emit` argument (default\n`true`). Pass `false` to update state without dispatching an event.\n\nCall `destroy()` when removing the element from the DOM to detach listeners.\nAfter mutating light DOM (e.g. swapping the hidden input), call `destroy()` then\n`init()`:\n\n```js\n$switch.destroy();\n// mutate light DOM…\n$switch.init();\n```\n\n## Events\n\n| Event | Cancelable | Detail | Description |\n| ----- | ---------- | ------ | ----------- |\n| `switch:activate` | Yes | `{ el }` | Fired before the switch turns on. Cancel to abort. |\n| `switch:deactivate` | Yes | `{ el }` | Fired before the switch turns off. Cancel to abort. |\n\n```js\nimport { EVENTS } from \"@agencecinq/utils\";\n\n$switch.addEventListener(EVENTS.SWITCH_ACTIVATE, () => {\n  console.log(\"activated\");\n});\n\n$switch.addEventListener(EVENTS.SWITCH_DEACTIVATE, () => {\n  console.log(\"deactivated\");\n});\n```\n\n## Build setup\n\n```bash\npnpm -C packages/switch build\n```\n\n## Acknowledgments\n\n- [Switch Pattern (WAI-ARIA Practices)](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)\n- [`@19h47/switch`](https://github.com/19h47/19h47-switch) — original implementation\n","readmeFilename":"README.md"}