Component field guide

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

LIVE COMPONENT

WelkCheckBox

A labeled native checkbox for independent on/off choices. Use defaultChecked for local state or checked plus onChange for controlled state. Native form submission and reset behavior are retained.

Keep it playful

Usage

React / TSX

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

<WelkCheckBox label="Keep it playful" defaultChecked />

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

Variants and behavior

Unchecked, checked, disabled, and native indeterminate states; 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.

Unchecked

Click the label or use Space to select.

Optional extra

Key propsdefaultChecked={false}

Checked

An uncontrolled checkbox starts selected and remains editable.

Include bonus panel

Key propsdefaultChecked

Indeterminate

A partial selection is set through the native input ref, not a JSX prop. Clicking resolves it.

Partially selected

Key propsref.current.indeterminate = true

Disabled states

Disabled checkboxes retain their checked appearance but cannot change.

Disabled uncheckedDisabled checked

Key propsdisabled / disabled defaultChecked

Usage notes and accessibility

Use checkboxes for independent choices or multiple selections. For exactly one option from a set, use WelkRadioGroup instead.
Read event.currentTarget.checked in onChange for controlled state. The native value is the form submission value, not the checked boolean.
Indeterminate is a native DOM property set through the forwarded ref; it is not a prop and is independent of checked. Keep a select-all controller synchronized with its child choices.

Props

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

WelkCheckBox 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.

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 is fixed to checkbox; size and children are omitted. Native value and defaultValue remain available.

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.