Initial docs (#61)
Add initial documentation site. Co-authored-by: ambiguous48 <33713262+ambiguous48@users.noreply.github.com>
This commit is contained in:
rgossiaux
318
src/routes/docs/switch.svx
Normal file
318
src/routes/docs/switch.svx
Normal file
@@ -0,0 +1,318 @@
|
||||
# Switch
|
||||
|
||||
<script>
|
||||
import Preview from "./_Preview.svelte";
|
||||
</script>
|
||||
|
||||
<Preview url="examples/switch" code="" class="h-[180px] bg-teal-300"/>
|
||||
|
||||
## Basic example
|
||||
|
||||
Switches are built using the `Switch` component. You can toggle your switch by clicking directly on the component or by pressing the spacebar while it's focused.
|
||||
|
||||
Toggling the switch fires the `change` event with a negated version of the `checked` value.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import { Switch } from "@rgossiaux/svelte-headlessui";
|
||||
|
||||
let enabled = false;
|
||||
</script>
|
||||
|
||||
<Switch
|
||||
checked={enabled}
|
||||
on:change={(e) => (enabled = e.detail)}
|
||||
class={enabled ? "switch switch-enabled" : "switch switch-disabled"}
|
||||
>
|
||||
<span class="sr-only">Enable notifications</span>
|
||||
<span class="toggle" class:toggle-on={enabled} class:toggle-off={!enabled} />
|
||||
</Switch>
|
||||
|
||||
<style>
|
||||
:global(.switch) {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
border-radius: 9999px;
|
||||
height: 1.5rem;
|
||||
width: 2.75rem;
|
||||
}
|
||||
|
||||
:global(.switch-enabled) {
|
||||
/* Blue */
|
||||
background-color: rgb(37 99 235);
|
||||
}
|
||||
|
||||
:global(.switch-disabled) {
|
||||
/* Gray */
|
||||
background-color: rgb(229 231 235);
|
||||
}
|
||||
|
||||
.sr-only {
|
||||
position: absolute;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
padding: 0;
|
||||
margin: -1px;
|
||||
overflow: hidden;
|
||||
clip: rect(0, 0, 0, 0);
|
||||
white-space: nowrap;
|
||||
border-width: 0;
|
||||
}
|
||||
|
||||
.toggle {
|
||||
display: inline-block;
|
||||
width: 1rem;
|
||||
height: 1rem;
|
||||
background-color: rgb(255 255 255);
|
||||
border-radius: 9999px;
|
||||
}
|
||||
|
||||
.toggle-on {
|
||||
transform: translateX(1.1rem);
|
||||
}
|
||||
|
||||
.toggle-off {
|
||||
transform: translateX(-0.25rem);
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
[See here](general-concepts#component-styling) for some general notes on styling the components in this library.
|
||||
|
||||
## Using a custom label
|
||||
|
||||
By default, the `Switch` renders a `<button>` as well as whatever children you pass into it. This can make it harder to implement certain UIs, since the children will be nested within the button.
|
||||
|
||||
In these situations, you can use the `SwitchGroup` component for more flexibility.
|
||||
|
||||
This example demonstrates how to use the `SwitchGroup`, `Switch`, and `SwitchLabel` components to render a label as a sibling to a button. Note that `SwitchLabel` is used alongside a `Switch`, and both must be rendered within a parent `SwitchGroup`.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import {
|
||||
Switch,
|
||||
SwitchLabel,
|
||||
SwitchGroup,
|
||||
} from "@rgossiaux/svelte-headlessui";
|
||||
|
||||
let enabled = false;
|
||||
</script>
|
||||
|
||||
<SwitchGroup>
|
||||
<div class="switch-container">
|
||||
<SwitchLabel class="switch-label">Enable notifications</SwitchLabel>
|
||||
<Switch
|
||||
checked={enabled}
|
||||
on:change={(e) => (enabled = e.detail)}
|
||||
class={enabled ? "switch switch-enabled" : "switch switch-disabled"}
|
||||
>
|
||||
<span class="sr-only">Enable notifications</span>
|
||||
<span
|
||||
class="toggle"
|
||||
class:toggle-on={enabled}
|
||||
class:toggle-off={!enabled}
|
||||
/>
|
||||
</Switch>
|
||||
</div>
|
||||
</SwitchGroup>
|
||||
|
||||
<style>
|
||||
.switch-container {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
:global(.switch-label) {
|
||||
margin-right: 1rem;
|
||||
}
|
||||
|
||||
:global(.switch) {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
border-radius: 9999px;
|
||||
height: 1.5rem;
|
||||
width: 2.75rem;
|
||||
transition-property: color, background-color, border-color,
|
||||
text-decoration-color, fill, stroke;
|
||||
transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
|
||||
transition-duration: 150ms;
|
||||
}
|
||||
|
||||
:global(.switch:focus) {
|
||||
outline: 2px solid transparent;
|
||||
outline-offset: 2px;
|
||||
box-shadow: 0 0 0 2px rgb(99 102 241);
|
||||
}
|
||||
|
||||
:global(.switch-enabled) {
|
||||
/* Blue */
|
||||
background-color: rgb(37 99 235);
|
||||
}
|
||||
|
||||
:global(.switch-disabled) {
|
||||
/* Gray */
|
||||
background-color: rgb(229 231 235);
|
||||
}
|
||||
|
||||
.sr-only {
|
||||
position: absolute;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
padding: 0;
|
||||
margin: -1px;
|
||||
overflow: hidden;
|
||||
clip: rect(0, 0, 0, 0);
|
||||
white-space: nowrap;
|
||||
border-width: 0;
|
||||
}
|
||||
|
||||
.toggle {
|
||||
display: inline-block;
|
||||
width: 1rem;
|
||||
height: 1rem;
|
||||
background-color: rgb(255 255 255);
|
||||
border-radius: 9999px;
|
||||
transition-property: transform;
|
||||
}
|
||||
|
||||
.toggle-on {
|
||||
transform: translateX(1.1rem);
|
||||
}
|
||||
|
||||
.toggle-off {
|
||||
transform: translateX(-0.25rem);
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
By default, clicking a `SwitchLabel` will toggle the switch, just like labels in native HTML checkboxes do. If you'd like to make the label non-clickable (which you might if it doesn't make sense for your design), you can add a `passive` prop to the `SwitchLabel` component:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import {
|
||||
Switch,
|
||||
SwitchLabel,
|
||||
SwitchGroup,
|
||||
} from "@rgossiaux/svelte-headlessui";
|
||||
|
||||
let enabled = false;
|
||||
</script>
|
||||
|
||||
<SwitchGroup>
|
||||
<SwitchLabel passive>Enable notifications</SwitchLabel>
|
||||
<Switch checked={enabled} on:change={(e) => (enabled = e.detail)}>
|
||||
<!-- ... -->
|
||||
</Switch>
|
||||
</SwitchGroup>
|
||||
```
|
||||
|
||||
## Transitions
|
||||
|
||||
Because switches are always rendered to the DOM (rather than being mounted/unmounted like other components in the library), there's generally no need to use the provided `Transition` component. You can just use CSS transitions or Svelte's transition directives:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import {
|
||||
Switch,
|
||||
SwitchLabel,
|
||||
SwitchGroup,
|
||||
} from "@rgossiaux/svelte-headlessui";
|
||||
|
||||
let enabled = false;
|
||||
</script>
|
||||
|
||||
<Switch checked={enabled} on:change={(e) => (enabled = e.detail)}>
|
||||
<span class="toggle" class:enabled>
|
||||
<!-- ... -->
|
||||
</span></Switch
|
||||
>
|
||||
|
||||
<style>
|
||||
.toggle {
|
||||
transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
|
||||
transition-duration: 150ms;
|
||||
transition-property: transform;
|
||||
}
|
||||
|
||||
.enabled {
|
||||
transform: translateX(1rem);
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
## Accessibility notes
|
||||
|
||||
### Labels
|
||||
|
||||
By default, the children of a `Switch` will be used as the label for screen readers. If you're using `SwitchLabel`, the content of your `Switch` component will be ignored by assistive technologies.
|
||||
|
||||
### Mouse interaction
|
||||
|
||||
Clicking a `Switch` or a `SwitchLabel` toggles the switch on and off.
|
||||
|
||||
### Keyboard interaction
|
||||
|
||||
When the `horizontal` prop is set, the `<ArrowUp>` and `<ArrowDown>` below become `<ArrowLeft>` and `<ArrowRight>`:
|
||||
|
||||
| Command | Description |
|
||||
| ------------------------------------ | ------------------ |
|
||||
| `<Space>` when a `Switch` is focused | Toggles the switch |
|
||||
|
||||
### Other
|
||||
|
||||
All relevant ARIA attributes are automatically managed.
|
||||
|
||||
For a full reference on all accessibility features implemented in `Switch`, see <a href="https://www.w3.org/TR/wai-aria-practices-1.2/#switch">the ARIA spec on Switch</a>.
|
||||
|
||||
## Component API
|
||||
|
||||
### Switch
|
||||
|
||||
The main switch component.
|
||||
|
||||
| Prop | Default | Type | Description |
|
||||
| --------- | -------- | --------- | ----------------------------------------- |
|
||||
| `as` | `button` | `string` | The element the `Switch` should render as |
|
||||
| `checked` | `false` | `boolean` | Whether the switch is checked |
|
||||
|
||||
| Slot prop | Type | Description |
|
||||
| --------- | --------- | ----------------------------- |
|
||||
| `checked` | `boolean` | Whether the switch is checked |
|
||||
|
||||
This component also dispatches a custom event, which is listened to using the Svelte `on:` directive:
|
||||
|
||||
| Event name | Type of event `.detail` | Description |
|
||||
| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `change` | `T` | Dispatched when a `Switch` is toggled; the event `detail` contains the new value of the switch |
|
||||
|
||||
### SwitchLabel
|
||||
|
||||
A label that can be used for more control over the text your switch will announce to screenreaders. Renders an element that is linked to the `Switch` via the `aria-labelledby` attribute and an autogenerated id.
|
||||
|
||||
| Prop | Default | Type | Description |
|
||||
| ---- | ------- | -------- | ---------------------------------------------- |
|
||||
| `as` | `label` | `string` | The element the `SwitchLabel` should render as |
|
||||
|
||||
### SwitchDescription
|
||||
|
||||
This is the description for your switch. When this is used, it will set the `aria-describedby` on the switch.
|
||||
|
||||
| Prop | Default | Type | Description |
|
||||
| ---- | ------- | -------- | ---------------------------------------------------- |
|
||||
| `as` | `p` | `string` | The element the `SwitchDescription` should render as |
|
||||
|
||||
| Slot prop | Type | Description |
|
||||
| --------- | --------- | --------------------------------- |
|
||||
| `open` | `boolean` | Whether or not the switch is open |
|
||||
|
||||
### SwitchGroup
|
||||
|
||||
Used to wrap a `Switch` together with a `SwitchLabel` and/or `SwitchDescription`
|
||||
|
||||
| Prop | Default | Type | Description |
|
||||
| ---- | ------- | -------- | ---------------------------------------------- |
|
||||
| `as` | `div` | `string` | The element the `SwitchGroup` should render as |
|
||||
Reference in New Issue
Block a user