Switch

A toggleable control that changes between two states when activated.

Enable notifications

import { component$, useStyles$ } from "@builder.io/qwik";
import { Switch } from "@kunai-consulting/qwik";
import styles from "./switch-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Switch.Root class="switch-root">
      <Switch.Trigger class="switch-trigger">
        <Switch.Thumb class="switch-thumb" />
      </Switch.Trigger>
      <Switch.Label>Enable notifications</Switch.Label>
    </Switch.Root>
  );
});

Features

WAI ARIA Switch design pattern
Hidden native input for form integration
Controlled and uncontrolled state management
Error state handling with aria-errormessage
Support for required/disabled states
Custom labels and descriptions with ARIA support
Keyboard navigation (Space/Enter)
Form binding support
Toggle animation support via thumb component
Customizable styling through data attributes

Anatomy

Part	Description
<Switch.Root>	Root component that manages the switch state and context
<Switch.Trigger>	Interactive element that toggles the switch state
<Switch.Thumb>	Visual indicator that moves to reflect the checked state
<Switch.Label>	Text label associated with the switch
<Switch.Description>	Additional descriptive text for the switch
<Switch.ErrorMessage>	Error message displayed when the switch is in an error state
<Switch.HiddenInput>	Hidden native input for form integration

Examples

Basic Usage

The most basic switch implementation includes a trigger, thumb, and label. The switch can be controlled through mouse clicks or keyboard interactions.

Enable notifications

Status: Notifications are enabled

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Switch } from "@kunai-consulting/qwik";
import styles from "./switch-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  const isCheckedSig = useSignal(true);

  return (
    <div>
      <Switch.Root class="switch-root" bind:checked={isCheckedSig}>
        <Switch.Trigger class="switch-trigger">
          <Switch.Thumb class="switch-thumb" />
        </Switch.Trigger>
        <Switch.Label>Enable notifications</Switch.Label>
      </Switch.Root>

      <div style={{ marginTop: "1rem", fontWeight: "bold" }}>
        Status:{" "}
        {isCheckedSig.value ? "Notifications are enabled" : "Notifications are disabled"}
      </div>
    </div>
  );
});

In this example, we demonstrate:

Using bind:checked for state management
Basic switch structure with Root, Trigger, Thumb, and Label components
Visual feedback showing the current state

Visual Features

Description Text

Add supplementary information to the switch using the Description component.

Enable notifications

(Receive notifications about important updates)

import { component$, useStyles$ } from "@builder.io/qwik";
import { Switch } from "@kunai-consulting/qwik";
import styles from "./switch-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Switch.Root class="switch-root">
      <Switch.Trigger class="switch-trigger">
        <Switch.Thumb class="switch-thumb" />
      </Switch.Trigger>
      <Switch.Label>Enable notifications</Switch.Label>
      <Switch.Description class="switch-description">
        (Receive notifications about important updates)
      </Switch.Description>
    </Switch.Root>
  );
});

This example shows:

Using Description component to provide additional context
Proper ARIA association between the switch and its description
Maintaining accessibility while adding more information

Advanced Usage

Disabled State

Switches can be disabled to prevent user interaction.

Disabled switch

import { component$, useStyles$ } from "@builder.io/qwik";
import { Switch } from "@kunai-consulting/qwik";
import styles from "./switch-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Switch.Root class="switch-root" disabled>
      <Switch.Trigger class="switch-trigger">
        <Switch.Thumb class="switch-thumb" />
      </Switch.Trigger>
      <Switch.Label>Disabled switch</Switch.Label>
    </Switch.Root>
  );
});

This example demonstrates:

Using the disabled prop to prevent interaction
Visual styling for disabled state
Maintaining proper ARIA attributes for accessibility

Form Integration

Switches can be integrated into forms with validation and error handling.

import { $, component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Switch } from "@kunai-consulting/qwik";
import styles from "./switch-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  const hasError = useSignal(false);

  const handleSubmit$ = $((e: SubmitEvent) => {
    const form = e.target as HTMLFormElement;
    if (!form.checkValidity()) {
      hasError.value = true;
    } else {
      hasError.value = false;
      console.log("Form submitted successfully!!!!!");
    }
  });

  return (
    <form
      preventdefault:submit
      noValidate
      onSubmit$={handleSubmit$}
      class="flex flex-col"
    >
      <Switch.Root
        required
        hasError={hasError.value}
        name="notifications"
        value="enabled"
        class="flex-col"
        onChange$={() => {
          hasError.value = false;
        }}
      >
        <div class="flex gap-2">
          <Switch.Trigger class="switch-trigger">
            <Switch.Thumb class="switch-thumb" />
          </Switch.Trigger>
          <Switch.Label>Enable notifications</Switch.Label>
          <Switch.HiddenInput />
        </div>

        {hasError.value && (
          <Switch.ErrorMessage class="switch-error-message">
            This field is required
          </Switch.ErrorMessage>
        )}
      </Switch.Root>

      <button type="submit" class="mt-4 px-4 py-2 bg-blue-500 text-white rounded">
        Save preferences
      </button>
    </form>
  );
});

This example showcases:

Form integration with name and value props
Required field validation
Error message display using ErrorMessage component
Error state handling with hasError prop
Hidden input management for form submission

Component State

Using Component State

The Switch component accepts several state-related props:

checked - Controls the checked state
disabled - Disables user interaction
required - Makes the switch a required form field
name - Sets the form field name
value - Sets the form submission value

State Interactions

Handling State Changes

The Switch component provides the onChange$ prop to handle state changes:

<Switch.Root
  onChange$={(checked) => {
    console.log(`Switch is now ${checked ? 'on' : 'off'}`);
  }}
>
  {/* ... */}
</Switch.Root>

Form Integration

As shown in the Form Integration example above, the Switch component integrates seamlessly with forms through:

Automatic form value submission
Required field validation
Error state handling

And can be configured for form integration with the following props:

name - Form field identifier
value - Value submitted with the form
required - Enforces field requirement
hasError - Controls error state display

Error State Management

The Switch supports error state handling through:

The hasError prop to indicate an error state
The ErrorMessage component to display error messages
Proper ARIA attributes for accessibility

As demonstrated in the Form Integration example, error states can be managed dynamically based on form validation or other conditions.

State Persistence

The Switch maintains its state across:

User interactions (clicks and keyboard events)
Form submissions
Focus changes This ensures a consistent user experience while maintaining proper form functionality.

Default Values

The Switch component initializes with these default configurations:

{
  checked: false,
  disabled: false,
  required: false,
  name: "",
  value: ""
}

Advanced Configuration

Component Structure

The Switch uses a compound component pattern with these required elements:

Root - Container and state manager
Trigger - Interactive element
Thumb - Visual indicator
Label - Text identifier

Optional components include:

Description
ErrorMessage
HiddenInput

Technical Constraints

The Trigger component must be a direct child of Root
The Thumb component must be within the Trigger
Form integration requires the HiddenInput component
Error messages require both hasError prop and ErrorMessage component These constraints ensure proper functionality and accessibility compliance.

API Reference

Switch Root

Inherits from: <div />

Props

Prop	Type	Default
checked	boolean	false
disabled	boolean	false
required	boolean	false
name	string	""
value	string	""

Data Attributes

Attribute	Description
data-qds-switch-root	Present on the root element
data-checked	Indicates whether the switch is currently checked
data-disabled	Indicates whether the switch is currently disabled
data-error	Indicates whether the switch is in an error state

Switch Trigger

Inherits from: <button />

Data Attributes

Attribute	Description
data-qds-switch-trigger	Present on the trigger element
data-checked	Indicates whether the switch is currently checked
data-disabled	Indicates whether the switch is currently disabled

Switch Thumb

Inherits from: <div />

Data Attributes

Attribute	Description
data-qds-switch-thumb	Present on the thumb element
data-checked	Indicates whether the switch is currently checked
data-disabled	Indicates whether the switch is currently disabled

Switch Label

Inherits from: <label />

Data Attributes

Attribute	Description
data-qds-switch-label	Present on the label element

Switch Description

Inherits from: <div />

Data Attributes

Attribute	Description
data-qds-switch-description	Present on the description element

Switch Error Message

Inherits from: <div />

Data Attributes

Attribute	Description
data-qds-switch-error-message	Present on the error message element

Switch Hidden Input

Inherits from: <input />

Props

Prop	Type	Default	Description
type	"checkbox"	"checkbox"

Switch

Features

Anatomy

Examples

Basic Usage

Visual Features

Description Text

Advanced Usage

Disabled State

Form Integration

Component State

Using Component State

State-Related Props

State Interactions

Handling State Changes

Form Integration

Error State Management

State Persistence

Default Values

Advanced Configuration

Component Structure

Technical Constraints

API Reference

Switch Root

Props

Data Attributes

Switch Trigger

Data Attributes

Switch Thumb

Data Attributes

Switch Label

Data Attributes

Switch Description

Data Attributes

Switch Error Message

Data Attributes

Switch Hidden Input

Props