docs: Add switch documentation
This commit is contained in:
Adam Wathan
@@ -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. |
|
||||
|
||||
@@ -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. |
|
||||
|
||||
Reference in New Issue
Block a user