Switch

A control that allows the user to toggle between checked and not checked.

Code

import { Label, Switch } from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:items-center tw:space-x-2">
      <Switch id="automatic-substitutions" />
      <Label htmlFor="automatic-substitutions">Automatic substitutions</Label>
    </div>
  );
}

Description

Code

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
  Switch,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <Field orientation="horizontal" className="tw:max-w-sm">
      <FieldContent>
        <FieldLabel htmlFor="switch-inventory-updates">
          Share inventory updates
        </FieldLabel>
        <FieldDescription id="inventory-updates-description">
          Inventory updates are shared across locations and stop when syncing is
          disabled.
        </FieldDescription>
      </FieldContent>
      <Switch
        id="switch-inventory-updates"
        aria-describedby="inventory-updates-description"
      />
    </Field>
  );
}

Choice Card

Card-style selection where FieldLabel wraps the entire Field for a clickable card pattern.

Code

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
  Switch,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:w-full tw:max-w-sm">
      <FieldLabel htmlFor="switch-inventory-updates">
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Share inventory updates</FieldTitle>
            <FieldDescription>
              Inventory updates are shared across locations and stop when
              syncing is disabled.
            </FieldDescription>
          </FieldContent>
          <Switch id="switch-inventory-updates" />
        </Field>
      </FieldLabel>
      <FieldLabel htmlFor="switch-order-notifications">
        <Field orientation="horizontal">
          <FieldContent>
            <FieldTitle>Enable order notifications</FieldTitle>
            <FieldDescription>
              Receive notifications when an order needs attention.
            </FieldDescription>
          </FieldContent>
          <Switch id="switch-order-notifications" defaultChecked />
        </Field>
      </FieldLabel>
    </FieldGroup>
  );
}

Disabled

Add the disabled prop to the Switch component to disable the switch. Add the data-disabled prop to the Field component for styling.

Code

import { Field, FieldLabel, Switch } from "@falcon/ui-kit";

export function Example() {
  return (
    <Field orientation="horizontal" data-disabled className="tw:w-fit">
      <Switch id="switch-disabled-unchecked" disabled />
      <FieldLabel htmlFor="switch-disabled-unchecked">Disabled</FieldLabel>
    </Field>
  );
}

Invalid

Add the aria-invalid prop to the Switch component to indicate an invalid state. Add the data-invalid prop to the Field component for styling.

Code

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
  Switch,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <Field orientation="horizontal" className="tw:max-w-sm" data-invalid>
      <FieldContent>
        <FieldLabel htmlFor="switch-order-terms">
          Accept order terms and conditions
        </FieldLabel>
        <FieldDescription id="order-terms-description">
          You must accept the order terms and conditions to continue.
        </FieldDescription>
      </FieldContent>
      <Switch
        id="switch-order-terms"
        aria-describedby="order-terms-description"
        aria-invalid
      />
    </Field>
  );
}

Size

Use the size prop to change the size of the switch.

Code

import { Field, FieldGroup, FieldLabel, Switch } from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:w-full tw:max-w-[10rem]">
      <Field orientation="horizontal">
        <Switch id="switch-size-sm" size="sm" />
        <FieldLabel htmlFor="switch-size-sm">Small</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch id="switch-size-default" size="default" />
        <FieldLabel htmlFor="switch-size-default">Default</FieldLabel>
      </Field>
    </FieldGroup>
  );
}

API

Switch

Toggles a setting on or off. Renders a <span> element with a hidden <input>. The required thumb is built in, so the component does not accept children.

Props

checked

checked?: boolean

Whether the switch is currently active. Use defaultChecked for uncontrolled state.

className

className?: string | ((state: SwitchRootState) => string | undefined)

CSS class applied to the switch, or a function based on its state.

defaultChecked

defaultChecked?: boolean

Whether the switch is initially active. Use checked for controlled state.

disabled

disabled?: boolean

Whether the switch ignores user interaction.

form

form?: string

Identifies the form that owns the hidden input.

id

id?: string

ID of the hidden input, or of the root when nativeButton is true.

inputRef

inputRef?: React.Ref<HTMLInputElement>

Ref to the hidden input element.

name

name?: string

Identifies the field when a form is submitted.

nativeButton

nativeButton?: boolean

Whether render produces a native <button> element.

onCheckedChange

onCheckedChange?: ((checked: boolean, eventDetails: SwitchPrimitive.Root.ChangeEventDetails) => void)

Event handler called when the switch is activated or deactivated.

readOnly

readOnly?: boolean

Whether users can activate or deactivate the switch.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>

Allows replacing the switch element or composing it with another component.

required

required?: boolean

Whether users must activate the switch before submitting the form.

size

size?: "sm" | "default" = "default"

Control size. Defaults to "default".

style

style?: React.CSSProperties | ((state: SwitchRootState) => React.CSSProperties | undefined)

Style applied to the switch, or a function based on its state.

uncheckedValue

uncheckedValue?: string

Value submitted when the switch is off.

value

value?: string

Value submitted when the switch is on.