Switch Component

Overview

Switch works in two modes: single for simple on/off toggles and group for multi-select switch lists. It supports controlled state management, group keyboard navigation, disabled/readOnly states, error handling, and highly customizable styling through Tailwind or inline styles.

Use single mode for settings like notifications or themes, and group mode for selecting multiple options such as features, permissions, or preferences.

Option Structure

Group mode receives an options array. Each option needs a display label and a string value.

1type SwitchOption = {
2  label: string;
3  value: string;
4};

Import Component From Library

1import { Switch } from "@neuctra/ui";

The Switch component supports both single and group modes. No extra setup is required — just import and start using it.

Basic Usage Code

Start with a simple switch. The component supports both single toggle and group multi-select modes with full customization.

1import { useState } from 'react';
2import { Switch } from '@neuctra/ui';
3
4function BasicExample() {
5  const [checked, setChecked] = useState(false);
6
7  return (
8    <Switch
9      mode="single"
10      label="Enable notifications"
11      checked={checked}
12      onCheckedChange={setChecked}
13    />
14  );
15}

Group Usage Code

Use mode="group" when several independent switches should be controlled as a string array.

1import { useState } from 'react';
2import { Switch } from '@neuctra/ui';
3
4function SwitchGroupExample() {
5  const [selectedValues, setSelectedValues] = useState(['email']);
6
7  const options = [
8    { label: 'Email alerts', value: 'email' },
9    { label: 'SMS alerts', value: 'sms' },
10    { label: 'Product updates', value: 'updates' }
11  ];
12
13  return (
14    <Switch
15      mode="group"
16      name="notifications"
17      options={options}
18      selectedValues={selectedValues}
19      onChange={setSelectedValues}
20    />
21  );
22}

Single Mode

Default mode for simple on/off toggles.

Group Mode

Multi-select switch group using mode="group".

Disabled & ReadOnly

Use disabled to completely block interaction and dim the UI. Use readOnly when you want to display the current state but prevent any changes.

Error State

Display validation feedback using the error prop. This is useful in forms when a required toggle has not been enabled.

Sizes (iconSize)

Control the overall size of the switch using iconSize. This adjusts both the track and thumb proportionally.

Styling & Customization

The Switch component exposes multiple styling layers. You can customize the track, thumb, label, and layout using Tailwind classes or inline styles.

Props Table

All available props for the Switch component.

Common Mistakes

Pro Tips

• Use mode="group" for settings panels, permissions, filters.
• Use iconSize to scale switch without touching CSS.
• Combine switchClassName + Tailwind gradients for modern UI.
• Use readOnly for display-only preference screens.
• Use error for inline validation instead of external messages.
• Prefer controlled state (checked / selectedValues) for consistency.

Frequently Asked Questions