Forms & Inputs
Switch
A form-associated on/off switch. Works inside a native <form>, supports keyboard toggling, and mirrors native checkbox semantics for submission.
Preview
Section titled “Preview”<nana-switch>Enable notifications</nana-switch> <script lang="ts">
import { NanaSwitch } from '$lib/components/ui/switch';
let enabled = $state(true);
</script>
<div class="flex flex-col gap-3">
<NanaSwitch label="Email notifications" bind:checked={enabled} />
<NanaSwitch label="Weekly digest" />
<NanaSwitch label="Disabled" disabled />
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add switch --framework web-componentsnpx @nana-tec/ui add switch --framework svelteLands in src/lib/components/ui/switch/ as NanaSwitch.svelte, styled with Tailwind
classes that resolve to the design tokens. Requires Tailwind v4.
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/switch";
Copied in with npx @nana-tec/ui add switch? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
<nana-switch>Enable notifications</nana-switch><script lang="ts"> import { NanaSwitch } from '$lib/components/ui/switch';
let enabled = $state(true);</script>
<NanaSwitch label="Email notifications" bind:checked={enabled} />It is a real <input type="checkbox"> under the visual track, so it submits with
a form and announces as a switch. checked is $bindable.
<nana-switch size="sm">Small</nana-switch>
<nana-switch size="md">Medium</nana-switch>
<nana-switch size="lg">Large</nana-switch> States
Section titled “States”<nana-switch checked>On</nana-switch>
<nana-switch>Off</nana-switch>
<nana-switch checked disabled>Disabled on</nana-switch>
<nana-switch disabled>Disabled off</nana-switch> Errors
Section titled “Errors”Set invalid to mark it invalid. error-message shows beneath it only while invalid is set, and is linked to the control as its description.
<nana-switch invalid error-message="Turn this on to receive alerts.">
Enable notifications
</nana-switch> Toggling the switch clears invalid.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | On/off state. |
description | description | string | undefined | — | Secondary descriptive text. |
disabled | disabled | boolean | false | Disable the control. |
errorMessage | error-message | string | '' | Error under the field while it is invalid, in the error part with role="alert". |
invalid | invalid | boolean | false | Marks the field invalid and shows error-message in place of the helper text. |
label | label | string | undefined | — | Convenience label text (slotted content wins). |
name | name | string | '' | Form field name. |
required | required | boolean | false | Mark as required for form validation. |
size | size | SwitchSize | 'md' | Control size. |
value | value | string | 'on' | Submitted value when checked (default "on"). |
Events
| Event | Description |
|---|---|
nana-change | Fired on toggle (detail.checked). |
Slots
| Slot | Description |
|---|---|
(default) | The label (overrides the label attribute). |
description | Secondary descriptive text. |
CSS parts
| Part | Description |
|---|---|
::part(base) | The clickable row. |
::part(control) | The track. |
::part(thumb) | The sliding thumb. |
::part(label) | The label text. |
::part(text) | The text |
::part(required) | The required |
::part(description) | The description |
::part(error) | The error message, shown while invalid is set |
CSS custom properties
| Property | Description |
|---|---|
--nana-switch-accent | Checked track colour. |
--nana-switch-thumb | Thumb colour. |
NanaSwitch
| Prop | Type | Default |
|---|---|---|
size | SwitchSize | 'md' |
checkedbind: | boolean | false |
label | string | |
description | string | |
invalidbind: | boolean | false |
errorMessage | string | |
children | Snippet | |
onCheckedChange | (checked: boolean) => void |
Also accepts Omit<HTMLInputAttributes, 'class' | 'size' | 'type' | 'checked'>.