Component field guide

Explore live variants, compare states, and learn every prop. Pick a component to start.

LIVE COMPONENT

WelkSwitch

A native checkbox exposed as a switch with a regular pill track, circular thumb, comic colors, and animated sliding. Use checked/onCheckedChange for controlled state or defaultChecked for native local state. The visible label is also clickable.

Hero mode

Usage

React / TSX

import { WelkSwitch } from "@welkui/react";

<WelkSwitch label="Hero mode" defaultChecked
  onCheckedChange={(checked) => console.log(checked)} />

Import @welkui/react/styles.css once in your app. Stateful snippets belong inside a React component.

Variants and behavior

Off, on and disabled states. The geometry is not distorted; there is no variant prop.

Visual variant gallery

These are real components, not screenshots. Compare their appearance and try the controls. Key props below each preview show what changes; use the usage example above for imports and component setup.

Off

Click the label or press Space on the switch to toggle it.

Enable bonus mode

Key propsdefaultChecked={false}

On

An uncontrolled switch starts enabled and stays editable.

Bonus mode enabled

Key propsdefaultChecked

Controlled feedback

A parent-owned boolean updates the switch and the visible output.

Live settingCurrent value: off

Key propschecked={enabled} onCheckedChange={setEnabled}

Disabled states

Both off and on states remain readable without accepting changes.

Locked offLocked on

Key propsdisabled / disabled defaultChecked

Usage notes and accessibility

Use for a setting that takes effect immediately; use a checkbox for choosing an item before a later form submission.
checked/onCheckedChange is a convenient controlled boolean API. Native onChange is also available; defaultChecked leaves state with the input.
The label is clickable and Space toggles the focused switch. Preserve a meaningful label in both states rather than changing its action name each time.

Props

Required props are marked in the default column. Other props are optional. ReactNode accepts text or JSX.

WelkSwitch prop reference
Prop	Type	Default	Description
`label`	`ReactNode`	Required	Visible, accessible control label.
`checked`	`boolean`	Uncontrolled	Controlled checked state; update it through the change callback.
`defaultChecked`	`boolean`	false	Initial checked state for uncontrolled use.
`onChange`	`ChangeEventHandler<HTMLInputElement>`	Unset	Native change event; read event.currentTarget.checked.
`onCheckedChange`	`(checked: boolean) => void`	Unset	Boolean state callback in addition to native onChange.

Native props and refs

Inherits native input props except the fields replaced by this component's API: name, id, disabled, required, form, onBlur, onFocus, className, style, aria-* and data-* are supported. Forwards an input ref. type and role are fixed to checkbox and switch; size and children are omitted.

Project setup, styling and Next.js

Import @welkui/react/styles.css once in your app entry or Next.js root layout. The previews use the default theme; override --welk-* CSS tokens in your app to customize it.

For Next.js, put hooks and event handlers in a component beginning with "use client". Keep state local to the component using the control. The library preserves its client boundaries and uses your installed React version.

Use defaultValue or defaultChecked for uncontrolled fields, or a state value and its change callback for controlled fields. Do not switch between these modes during the lifetime of a field.

Modal and notification examples start closed: use their Try buttons to see them. Disabled examples are deliberately non-interactive. Validate forms, uploads, authentication, and server responses in your application; these components only provide UI.