Skip to content

Commit d0720c2

Browse files
adamwathanadamwathan
committed
docs: Add switch documentation
1 parent a1fcf52 commit d0720c2

File tree

2 files changed

+283
-0
lines changed

2 files changed

+283
-0
lines changed

‎packages/@headlessui-react/README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1246,3 +1246,129 @@ function MyListbox() {
12461246
| `active` | Boolean | Whether or not the option is the active/focused option in the list. |
12471247
| `selected` | Boolean | Whether or not the option is the selected option in the list. |
12481248
| `disabled` | Boolean | Whether or not the option is the disabled for keyboard navigation and ARIA purposes. |
1249+
1250+
## Switch (Toggle)
1251+
1252+
[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuireact-switch-example-y40i1?file=/src/App.js)
1253+
1254+
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.
1255+
1256+
- [Basic example](#basic-example-3)
1257+
- [Using a custom label](#using-a-custom-label)
1258+
- [Component API](#component-api-3)
1259+
1260+
### Basic example
1261+
1262+
Switches are built using the `Switch` component. Optionally you can also use the `Switch.Group` and `Switch.Label` components.
1263+
1264+
```jsx
1265+
import { useState } from 'react'
1266+
import { Switch } from '@headlessui/react'
1267+
1268+
function NotificationsToggle() {
1269+
const [enabled, setEnabled] = useState(false)
1270+
1271+
return (
1272+
<Switch
1273+
checked={enabled}
1274+
onChange={setEnabled}
1275+
className={`${switchValue ? "bg-blue-600" : "bg-gray-200"} relative inline-flex h-6 rounded-full w-8`}
1276+
>
1277+
<span className="sr-only">Enable notifications</span>
1278+
<span
1279+
className={`${enabled ? "translate-x-4" : "translate-x-0"} inline-block w-4 h-4 transform bg-white rounded-full`}
1280+
/>
1281+
</Switch>
1282+
)
1283+
}
1284+
```
1285+
1286+
### Using a custom label
1287+
1288+
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`.
1289+
1290+
Clicking the label will toggle the switch state, like you'd expect from a native checkbox.
1291+
1292+
```jsx
1293+
import { useState } from 'react'
1294+
import { Switch } from '@headlessui/react'
1295+
1296+
function NotificationsToggle() {
1297+
const [enabled, setEnabled] = useState(false)
1298+
1299+
return (
1300+
<Switch.Group>
1301+
<Switch.Label>Enable notifications</Switch.Label>
1302+
<Switch
1303+
checked={enabled}
1304+
onChange={setEnabled}
1305+
className={`${switchValue ? "bg-blue-600" : "bg-gray-200"} relative inline-flex h-6 rounded-full w-8`}
1306+
>
1307+
<span
1308+
className={`${enabled ? "translate-x-4" : "translate-x-0"} inline-block w-4 h-4 transform bg-white rounded-full`}
1309+
/>
1310+
</Switch>
1311+
</Switch.Group>
1312+
)
1313+
}
1314+
```
1315+
1316+
### Component API
1317+
1318+
#### Switch
1319+
1320+
```jsx
1321+
<Switch checked={checkedState} onChange={setCheckedState}>
1322+
<span className="sr-only">Enable notifications</span>
1323+
{/* ... */}
1324+
</Switch>
1325+
```
1326+
1327+
##### Props
1328+
1329+
| Prop | Type | Default | Description |
1330+
| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
1331+
| `as` | String \| Component | `button` | The element or component the `Switch` should render as. |
1332+
| `checked` | Boolean | | Whether or not the switch is checked. |
1333+
| `onChange` | `(value: boolean): void` | | The function to call when the switch is toggled. |
1334+
1335+
##### Render prop object
1336+
1337+
| Prop | Type | Description |
1338+
| ------ | ------- | ----------------------------------- |
1339+
| `checked` | Boolean | Whether or not the switch is checked. |
1340+
1341+
1342+
#### Switch.Label
1343+
1344+
```jsx
1345+
<Switch.Group>
1346+
<Switch.Label>Enable notifications</Switch.Label>
1347+
<Switch checked={enabled} onChange={setEnabled} className="...">
1348+
{/* ... */}
1349+
</Switch>
1350+
</Switch.Group>
1351+
```
1352+
1353+
##### Props
1354+
1355+
| Prop | Type | Default | Description |
1356+
| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
1357+
| `as` | String \| Component | `label` | The element or component the `Switch.Label` should render as. |
1358+
1359+
#### Switch.Group
1360+
1361+
```jsx
1362+
<Switch.Group>
1363+
<Switch.Label>Enable notifications</Switch.Label>
1364+
<Switch checked={enabled} onChange={setEnabled} className="...">
1365+
{/* ... */}
1366+
</Switch>
1367+
</Switch.Group>
1368+
```
1369+
1370+
##### Props
1371+
1372+
| Prop | Type | Default | Description |
1373+
| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
1374+
| `as` | String \| Component | `React.Fragment` _(no wrapper element)_| The element or component the `Switch.Group` should render as. |

‎packages/@headlessui-vue/README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1037,3 +1037,160 @@ export default {
10371037
| `active` | Boolean | Whether or not the option is the active/focused option in the list. |
10381038
| `selected` | Boolean | Whether or not the option is the selected option in the list. |
10391039
| `disabled` | Boolean | Whether or not the option is the disabled for keyboard navigation and ARIA purposes. |
1040+
1041+
## Switch (Toggle)
1042+
1043+
[View live demo on CodeSandbox](https://codesandbox.io/s/headlessuivue-switch-example-8ycp6?file=/src/App.vue)
1044+
1045+
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.
1046+
1047+
- [Basic example](#basic-example-3)
1048+
- [Using a custom label](#using-a-custom-label)
1049+
- [Component API](#component-api-3)
1050+
1051+
### Basic example
1052+
1053+
Switches are built using the `Switch` component. Optionally you can also use the `SwitchGroup` and `SwitchLabel` components.
1054+
1055+
```vue
1056+
<template>
1057+
<Switch
1058+
as="button"
1059+
v-model="switchValue"
1060+
class="relative inline-flex h-6 rounded-full w-8"
1061+
:class="switchValue ? 'bg-blue-600' : 'bg-gray-200'"
1062+
v-slot="{ checked }"
1063+
>
1064+
<span
1065+
class="inline-block w-4 h-4 transform bg-white rounded-full"
1066+
:class="{ 'translate-x-5': checked, 'translate-x-0': !checked }"
1067+
/>
1068+
</Switch>
1069+
</template>
1070+
1071+
<script>
1072+
import { ref } from "vue";
1073+
import { SwitchGroup, Switch, SwitchLabel } from "@headlessui/vue";
1074+
1075+
export default {
1076+
components: {
1077+
SwitchGroup,
1078+
Switch,
1079+
SwitchLabel,
1080+
},
1081+
setup() {
1082+
const switchValue = ref(false);
1083+
1084+
return {
1085+
switchValue,
1086+
};
1087+
},
1088+
};
1089+
</script>
1090+
```
1091+
1092+
### Using a custom label
1093+
1094+
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`.
1095+
1096+
Clicking the label will toggle the switch state, like you'd expect from a native checkbox.
1097+
1098+
```vue
1099+
<template>
1100+
<SwitchGroup as="div" class="flex items-center space-x-4">
1101+
<SwitchLabel>Enable notifications</SwitchLabel>
1102+
1103+
<Switch
1104+
as="button"
1105+
v-model="switchValue"
1106+
class="relative inline-flex h-6 rounded-full w-8"
1107+
:class="switchValue ? 'bg-blue-600' : 'bg-gray-200'"
1108+
v-slot="{ checked }"
1109+
>
1110+
<span
1111+
class="inline-block w-4 h-4 transform bg-white rounded-full"
1112+
:class="{ 'translate-x-5': checked, 'translate-x-0': !checked }"
1113+
/>
1114+
</Switch>
1115+
</SwitchGroup>
1116+
</template>
1117+
1118+
<script>
1119+
import { ref } from "vue";
1120+
import { SwitchGroup, Switch, SwitchLabel } from "@headlessui/vue";
1121+
1122+
export default {
1123+
components: {
1124+
SwitchGroup,
1125+
Switch,
1126+
SwitchLabel,
1127+
},
1128+
setup() {
1129+
const switchValue = ref(false);
1130+
1131+
return {
1132+
switchValue,
1133+
};
1134+
},
1135+
};
1136+
</script>
1137+
```
1138+
1139+
### Component API
1140+
1141+
#### Switch
1142+
1143+
```jsx
1144+
<Switch v-model="switchState">
1145+
<span class="sr-only">Enable notifications</span>
1146+
<!-- ... -->
1147+
</Switch>
1148+
```
1149+
1150+
##### Props
1151+
1152+
| Prop | Type | Default | Description |
1153+
| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
1154+
| `as` | String \| Component | `button` | The element or component the `Switch` should render as. |
1155+
| `v-model` | `T` | | The switch value. |
1156+
1157+
##### Slot props
1158+
1159+
| Prop | Type | Description |
1160+
| ------ | ------- | ----------------------------------- |
1161+
| `checked` | Boolean | Whether or not the switch is checked. |
1162+
1163+
1164+
#### Switch.Label
1165+
1166+
```jsx
1167+
<SwitchGroup>
1168+
<SwitchLabel>Enable notifications</SwitchLabel>
1169+
<Switch v-model="switchState">
1170+
<!-- ... -->
1171+
</Switch>
1172+
</SwitchGroup>
1173+
```
1174+
1175+
##### Props
1176+
1177+
| Prop | Type | Default | Description |
1178+
| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
1179+
| `as` | String \| Component | `label` | The element or component the `SwitchLabel` should render as. |
1180+
1181+
#### Switch.Group
1182+
1183+
```jsx
1184+
<SwitchGroup>
1185+
<SwitchLabel>Enable notifications</SwitchLabel>
1186+
<Switch v-model="switchState">
1187+
<!-- ... -->
1188+
</Switch>
1189+
</SwitchGroup>
1190+
```
1191+
1192+
##### Props
1193+
1194+
| Prop | Type | Default | Description |
1195+
| ---------- | ----------------------- | --------------------------------------- | -------------------------------------------------------- |
1196+
| `as` | String \| Component | `template` _(no wrapper element)_| The element or component the `SwitchGroup` should render as. |

0 commit comments

Comments
 (0)