Forms

Stable - @kikita-labs/ui v2.0.0

Switch

Native checkbox rendered as a switch while keeping native keyboard and form behavior.

Import

Use the directive on native checkbox inputs and pair it with kui-field for field-level wiring.

switch.ts
import { KuiField, KuiSwitch } from '@kikita-labs/ui';

Usage

Open in Playground

Keep native label text next to the switch and reserve switch for binary settings.

Control product and release notifications

<kui-field label="Notifications" hint="Control product and release notifications">
  <label class="switch-option">
    <input kuiSwitch type="checkbox" checked />
    <span>Enable notifications</span>
  </label>
</kui-field>

Sizes

Use the same size scale as other Kikita form controls.

<div class="switch-size-example">
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="xs" />
    <span>Extra small</span>
  </label>
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="sm" checked />
    <span>Small</span>
  </label>
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="md" checked />
    <span>Medium</span>
  </label>
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="lg" />
    <span>Large</span>
  </label>
</div>

Provider defaults

Set defaults.switch once for the application or for a subtree. Each option resolves as local input > defaults.switch.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        switch: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' — Component size. Takes precedence over the global defaults.size.

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' | undefinedundefinedSwitch size mapped to Kikita switch tokens. Resolved from defaults.switch.size, then the parent field, then the global defaults.size, then md.
invalidbooleanfalseMarks the switch invalid outside a kui-field error state. With [formField] the Field state wins.
idstring | undefinedundefinedExplicit id override. Inside kui-field, the field id is used when omitted.
KuiSwitchOptionsinterface-Shape of defaults.switch: size.

Accessibility

Switch adds role=switch while keeping the native checkbox element.

  • Render kuiSwitch on a native input[type=checkbox]; the directive adds role="switch" while the element keeps native checkbox semantics, keyboard support, and form participation.
  • Wrap the input in a native label so the switch text is the accessible name.
  • Space toggles the switch and Tab moves focus, matching native checkbox keyboard behavior; the directive does not add custom key handling.
  • Use kui-field for group label, hint, error, and aria-describedby wiring instead of building described-by attributes by hand.
  • Set the native disabled attribute to disable the control; use the directive's invalid input to mark it invalid outside a kui-field error state.
  • A required kui-field exposes aria-required on the switch, and the checked switch stays visible under forced-colors: active.
  • Use switch only for an immediate binary setting, not multi-choice selection.
  • Per the Kikita UI library's state coverage notes, Switch has local playground coverage for off, on, hover, focus, invalid, disabled, sizes, and field wiring, but a dedicated assistive-technology review has not been completed yet.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Switch.

  • The directive class is KuiSwitch; the Directive suffix is gone.
  • The default size moved to provideKuiDefaults({ switch: { size } }); the input is now undefined until set.
  • A required kui-field sets aria-required on the switch.
  • The checked and indeterminate states are covered by forced-colors, and disabled switches use the shared --kui-opacity-disabled.