From d0720c27c57defa55cdfda6bbc2a9397d6f51ddd Mon Sep 17 00:00:00 2001
From: Adam Wathan <adam.wathan@gmail.com>
Date: Mon, 5 Oct 2020 21:41:26 -0400
Subject: [PATCH] docs: Add switch documentation

---
 packages/@headlessui-react/README.md | 126 +++++++++++++++++++++
 packages/@headlessui-vue/README.md   | 157 +++++++++++++++++++++++++++
 2 files changed, 283 insertions(+)

diff --git a/packages/@headlessui-react/README.md b/packages/@headlessui-react/README.md
index 264554d..7bb89e9 100644
--- a/packages/@headlessui-react/README.md
+++ b/packages/@headlessui-react/README.md
@@ -1246,3 +1246,129 @@ function MyListbox() {
 | `active`   | Boolean | Whether or not the option is the active/focused option in the list.                  |
 | `selected` | Boolean | Whether or not the option is the selected option in the list.                        |
 | `disabled` | Boolean | Whether or not the option is the disabled for keyboard navigation and ARIA purposes. |
+
+## Switch (Toggle)
+
+[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuireact-switch-example-y40i1?file=/src/App.js)
+
+The `Switch` component and related child components are used to quickly build custom switch/toggle components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard support.
+
+- [Basic example](#basic-example-3)
+- [Using a custom label](#using-a-custom-label)
+- [Component API](#component-api-3)
+
+### Basic example
+
+Switches are built using the `Switch` component. Optionally you can also use the `Switch.Group` and `Switch.Label` components.
+
+```jsx
+import { useState } from 'react'
+import { Switch } from '@headlessui/react'
+
+function NotificationsToggle() {
+  const [enabled, setEnabled] = useState(false)
+
+  return (
+    <Switch
+      checked={enabled}
+      onChange={setEnabled}
+      className={`${switchValue ? "bg-blue-600" : "bg-gray-200"} relative inline-flex h-6 rounded-full w-8`}
+    >
+      <span className="sr-only">Enable notifications</span>
+      <span
+        className={`${enabled ? "translate-x-4" : "translate-x-0"} inline-block w-4 h-4 transform bg-white rounded-full`}
+      />
+    </Switch>
+  )
+}
+```
+
+### Using a custom label
+
+By default the `Switch` will use the contents as the label for screenreaders. If you need more control, you can render a `Switch.Label` outside of the `Switch`, as long as both the switch and label are within a parent `Switch.Group`.
+
+Clicking the label will toggle the switch state, like you'd expect from a native checkbox.
+
+```jsx
+import { useState } from 'react'
+import { Switch } from '@headlessui/react'
+
+function NotificationsToggle() {
+  const [enabled, setEnabled] = useState(false)
+
+  return (
+    <Switch.Group>
+      <Switch.Label>Enable notifications</Switch.Label>
+      <Switch
+        checked={enabled}
+        onChange={setEnabled}
+        className={`${switchValue ? "bg-blue-600" : "bg-gray-200"} relative inline-flex h-6 rounded-full w-8`}
+      >
+        <span
+          className={`${enabled ? "translate-x-4" : "translate-x-0"} inline-block w-4 h-4 transform bg-white rounded-full`}
+        />
+      </Switch>
+    </Switch.Group>
+  )
+}
+```
+
+### Component API
+
+#### Switch
+
+```jsx
+<Switch checked={checkedState} onChange={setCheckedState}>
+  <span className="sr-only">Enable notifications</span>
+  {/* ... */}
+</Switch>
+```
+
+##### Props
+
+| Prop       | Type                    | Default                                 | Description                                              |
+| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `as`       | String \| Component     | `button` | The element or component the `Switch` should render as. |
+| `checked`    | Boolean |                              | Whether or not the switch is checked.                                      |
+| `onChange` | `(value: boolean): void`      |                              | The function to call when the switch is toggled.      |
+
+##### Render prop object
+
+| Prop   | Type    | Description                         |
+| ------ | ------- | ----------------------------------- |
+| `checked` | Boolean | Whether or not the switch is checked. |
+
+
+#### Switch.Label
+
+```jsx
+<Switch.Group>
+  <Switch.Label>Enable notifications</Switch.Label>
+  <Switch checked={enabled} onChange={setEnabled} className="...">
+    {/* ... */}
+  </Switch>
+</Switch.Group>
+```
+
+##### Props
+
+| Prop       | Type                    | Default                                 | Description                                              |
+| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `as`       | String \| Component     | `label` | The element or component the `Switch.Label` should render as. |
+
+#### Switch.Group
+
+```jsx
+<Switch.Group>
+  <Switch.Label>Enable notifications</Switch.Label>
+  <Switch checked={enabled} onChange={setEnabled} className="...">
+    {/* ... */}
+  </Switch>
+</Switch.Group>
+```
+
+##### Props
+
+| Prop       | Type                    | Default                                 | Description                                              |
+| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `as`       | String \| Component     | `React.Fragment` _(no wrapper element)_| The element or component the `Switch.Group` should render as. |
diff --git a/packages/@headlessui-vue/README.md b/packages/@headlessui-vue/README.md
index f84fdc8..8f79d30 100644
--- a/packages/@headlessui-vue/README.md
+++ b/packages/@headlessui-vue/README.md
@@ -1037,3 +1037,160 @@ export default {
 | `active`   | Boolean | Whether or not the option is the active/focused option in the list.                  |
 | `selected` | Boolean | Whether or not the option is the selected option in the list.                        |
 | `disabled` | Boolean | Whether or not the option is the disabled for keyboard navigation and ARIA purposes. |
+
+## Switch (Toggle)
+
+[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-switch-example-8ycp6?file=/src/App.vue)
+
+The `Switch` component and related child components are used to quickly build custom switch/toggle components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard support.
+
+- [Basic example](#basic-example-3)
+- [Using a custom label](#using-a-custom-label)
+- [Component API](#component-api-3)
+
+### Basic example
+
+Switches are built using the `Switch` component. Optionally you can also use the `SwitchGroup` and `SwitchLabel` components.
+
+```vue
+<template>
+  <Switch
+    as="button"
+    v-model="switchValue"
+    class="relative inline-flex h-6 rounded-full w-8"
+    :class="switchValue ? 'bg-blue-600' : 'bg-gray-200'"
+    v-slot="{ checked }"
+  >
+    <span
+      class="inline-block w-4 h-4 transform bg-white rounded-full"
+      :class="{ 'translate-x-5': checked, 'translate-x-0': !checked }"
+    />
+  </Switch>
+</template>
+
+<script>
+import { ref } from "vue";
+import { SwitchGroup, Switch, SwitchLabel } from "@headlessui/vue";
+
+export default {
+  components: {
+    SwitchGroup,
+    Switch,
+    SwitchLabel,
+  },
+  setup() {
+    const switchValue = ref(false);
+
+    return {
+      switchValue,
+    };
+  },
+};
+</script>
+```
+
+### Using a custom label
+
+By default the `Switch` will use the contents as the label for screenreaders. If you need more control, you can render a `SwitchLabel` outside of the `Switch`, as long as both the switch and label are within a parent `SwitchGroup`.
+
+Clicking the label will toggle the switch state, like you'd expect from a native checkbox.
+
+```vue
+<template>
+  <SwitchGroup as="div" class="flex items-center space-x-4">
+    <SwitchLabel>Enable notifications</SwitchLabel>
+
+    <Switch
+      as="button"
+      v-model="switchValue"
+      class="relative inline-flex h-6 rounded-full w-8"
+      :class="switchValue ? 'bg-blue-600' : 'bg-gray-200'"
+      v-slot="{ checked }"
+    >
+      <span
+        class="inline-block w-4 h-4 transform bg-white rounded-full"
+        :class="{ 'translate-x-5': checked, 'translate-x-0': !checked }"
+      />
+    </Switch>
+  </SwitchGroup>
+</template>
+
+<script>
+import { ref } from "vue";
+import { SwitchGroup, Switch, SwitchLabel } from "@headlessui/vue";
+
+export default {
+  components: {
+    SwitchGroup,
+    Switch,
+    SwitchLabel,
+  },
+  setup() {
+    const switchValue = ref(false);
+
+    return {
+      switchValue,
+    };
+  },
+};
+</script>
+```
+
+### Component API
+
+#### Switch
+
+```jsx
+<Switch v-model="switchState">
+  <span class="sr-only">Enable notifications</span>
+  <!-- ... -->
+</Switch>
+```
+
+##### Props
+
+| Prop       | Type                    | Default                                 | Description                                              |
+| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `as`       | String \| Component     | `button` | The element or component the `Switch` should render as. |
+| `v-model` | `T` |                        | The switch value. |
+
+##### Slot props
+
+| Prop   | Type    | Description                         |
+| ------ | ------- | ----------------------------------- |
+| `checked` | Boolean | Whether or not the switch is checked. |
+
+
+#### Switch.Label
+
+```jsx
+<SwitchGroup>
+  <SwitchLabel>Enable notifications</SwitchLabel>
+  <Switch v-model="switchState">
+    <!-- ... -->
+  </Switch>
+</SwitchGroup>
+```
+
+##### Props
+
+| Prop       | Type                    | Default                                 | Description                                              |
+| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `as`       | String \| Component     | `label` | The element or component the `SwitchLabel` should render as. |
+
+#### Switch.Group
+
+```jsx
+<SwitchGroup>
+  <SwitchLabel>Enable notifications</SwitchLabel>
+  <Switch v-model="switchState">
+    <!-- ... -->
+  </Switch>
+</SwitchGroup>
+```
+
+##### Props
+
+| Prop       | Type                    | Default                                 | Description                                              |
+| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `as`       | String \| Component     | `template` _(no wrapper element)_| The element or component the `SwitchGroup` should render as. |