Switch

Install and import

Switch is in @dovetail-ds/react. Install it with React, if you haven't:

Guidelines

An instant on/off setting. Flipping it applies the change; there is no Save button.

Use it when

• A preference takes effect immediately: notifications, dark mode, autopay.

Don't use it when

• The value is submitted with a form. Use Checkbox; a switch that needs saving lies about when it took effect.
• The choice is not two opposite states.

Example

<Switch label="Autopay" hint="Charge the card on file each month" labelPosition="start" defaultChecked />

Variants

labelPosition="start" is the settings-row pattern: label left, switch pushed to the right edge.

Accessibility

Renders role="switch" on a real checkbox input, so state is announced as on/off rather than checked/unchecked.

Content

Label names the thing being switched, not the action. "Autopay", not "Turn on autopay".

Props

The typed contract, from Switch.d.ts.

import * as React from "react";

/** Instant on/off setting. The change applies the moment it is flipped. */
export interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange" | "type"> {
  label?: React.ReactNode;
  hint?: string;
  checked?: boolean;
  defaultChecked?: boolean;
  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
  disabled?: boolean;
  /** "start" puts the label on the left and pushes the switch right — the settings-row pattern. @default "end" */
  labelPosition?: "start" | "end";
}

export declare function Switch(props: SwitchProps): React.JSX.Element;

Tokens it reads

Every custom property Switch.jsx resolves, read from the source: 13 semantic, 1 primitive. Component tier first, because that is the one to reach for.

Open the graph

• semantic Shared roles. Override one and everything using that role moves with it.
• primitive Raw values. A component reading one directly is a deliberate exception.

Source

React only, no dependencies, every value a token.

import React from "react";

export function Switch({ label, hint, checked, defaultChecked = false, onChange, disabled = false, id, labelPosition = "end", style, ...rest }) {
  const [internal, setInternal] = React.useState(defaultChecked);
  const auto = React.useId();
  const switchId = id || auto;
  const isOn = checked !== undefined ? checked : internal;

  const handle = (e) => {
    if (checked === undefined) setInternal(e.target.checked);
    onChange && onChange(e);
  };

  const track = (
    <span
      aria-hidden="true"
      style={{
        flex: "none", position: "relative", width: 40, height: 24, borderRadius: "var(--dt-radius-pill)",
        background: isOn ? "var(--dt-surface-action)" : "var(--dt-border-strong)",
        transition: "background var(--dt-motion-micro)",
      }}
    >
      <span
        style={{
          position: "absolute", top: 3, left: isOn ? 19 : 3, width: 18, height: 18, borderRadius: "50%",
          background: "var(--dt-color-white)", boxShadow: "var(--dt-elevation-1)",
          transition: "left var(--dt-motion-micro)",
        }}
      />
    </span>
  );

  const text = (
    <span style={{ display: "flex", flexDirection: "column", gap: 2 }}>
      <span style={{ fontFamily: "var(--dt-text-body-sm-family)", fontSize: "var(--dt-text-body-sm-size)", lineHeight: "var(--dt-text-body-sm-line)", color: "var(--dt-text-primary)" }}>{label}</span>
      {hint && <span style={{ fontSize: "var(--dt-text-body-xs-size)", lineHeight: "var(--dt-text-body-xs-line)", color: "var(--dt-text-secondary)" }}>{hint}</span>}
    </span>
  );

  return (
    <div style={{ display: "flex", opacity: disabled ? 0.6 : 1, ...style }}>
      <input
        type="checkbox" role="switch" id={switchId} checked={isOn} onChange={handle} disabled={disabled}
        style={{ position: "absolute", opacity: 0, width: 0, height: 0 }}
        {...rest}
      />
      <label
        htmlFor={switchId}
        style={{
          display: "flex", alignItems: hint ? "flex-start" : "center", gap: "var(--dt-space-inline-sm)",
          cursor: disabled ? "not-allowed" : "pointer",
          justifyContent: labelPosition === "start" ? "space-between" : undefined,
          width: labelPosition === "start" ? "100%" : undefined,
          flexDirection: labelPosition === "start" ? "row-reverse" : "row",
        }}
      >
        {track}
        {text}
      </label>
    </div>
  );
}

In context

Switch also appears on the forms reference cards, alongside the rest of its family.

• FormsDetail