Switch

Tier: client

ImportCopy Anchor Link

import { Switch } from '@nizivo/react/switch';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/switch.css';

Static or interactiveCopy Anchor Link

Client. It always ships its client leaf, which wires it to a Field, and inside a Field also FieldScope. The server HTML is a native checkbox with role="switch", so it toggles and submits before hydration. How to choose.

InvalidCopy Anchor Link

With an error, an unchecked Switch draws a 1 px --nz-border-critical ring inside its track (--nz-border-width-default), as every Figma border is 1 px; the message under it, with its icon, carries the state. The checked track keeps its brand fill.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Switch } from '@nizivo/react/switch';

export function SwitchExample(): JSX.Element {
  return (
    <Switch name="online-store" defaultChecked>
      Online store
    </Switch>
  );
}

import type { JSX } from 'react';
import { Fieldset } from '@nizivo/react/fieldset';
import { Switch } from '@nizivo/react/switch';

export function SwitchStatesExample(): JSX.Element {
  return (
    <Fieldset legend="Billing emails" description="Sent to the billing contact.">
      <Switch name="billing" value="invoices" defaultChecked>
        Invoices
      </Switch>
      <Switch name="billing" value="usage">
        Usage reports
      </Switch>
      <Switch name="billing" value="failed" defaultChecked disabled>
        Failed payments (always on)
      </Switch>
      <Switch name="billing" value="digest" disabled>
        Weekly digest (unavailable)
      </Switch>
    </Fieldset>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Switch } from '@nizivo/react/switch';

export function SwitchFieldExample(): JSX.Element {
  return (
    <Field
      label="Wholesale"
      description="Show wholesale prices to approved buyers."
      error="Set a wholesale price list first."
    >
      <Switch name="wholesale">Enable wholesale</Switch>
    </Field>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

SwitchChangeReason type

import type { SwitchChangeReason } from '@nizivo/react/switch'

Every change comes from the native change event: a click, Space, or a click on the label.

type SwitchChangeReason = "input"

SwitchProps type

import type { SwitchProps } from '@nizivo/react/switch'

The props of Switch, listed above.

SwitchState type

import type { SwitchState } from '@nizivo/react/switch'

What a render function receives for the root <label>.

The render state of Switch, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-switch, .nz-switch-input, .nz-switch-label, .nz-switch-thumb.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• switch-input: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: switch-input (border), switch-input:checked (fill), switch-thumb (mark).

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: a native <input type="checkbox" role="switch"> (switch.client.tsx), which adds no key handling.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:11494
• Ghost masters: Figma node 745:286