Component field guide

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

LIVE COMPONENT

WelkRadio

A labeled native radio for one mutually exclusive option. Give related radios the same name and different values. Control checked/onChange individually or use WelkRadioGroup for a labeled options collection.

HeroSidekick

Usage

React / TSX

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

<WelkRadio label="Hero" name="role" value="hero" />
<WelkRadio label="Sidekick" name="role" value="sidekick" />

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

Variants and behavior

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

Shared-name options

The checked, unchecked, and disabled appearances in one native mutually exclusive group.

Choose one optionFirst optionSecond optionUnavailable option

Key propsname="shared-role" value="first" / value="second"

Disabled checked

A selected radio can remain checked while disabled.

Locked selected option

Key propsdisabled defaultChecked

Usage notes and accessibility

Related options must share a name and have different values. The browser then handles exclusive selection and keyboard movement within the group.
Provide a visible group label through a surrounding fieldset/legend, or use WelkRadioGroup. Individual option labels should be distinct and meaningful.
checked is the boolean selection state; value is the submitted choice. Read currentTarget.checked in onChange when managing individual controlled radios.

Props

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

WelkRadio 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.
`name`	`string`	Unset	Shared group name; required for native mutual exclusion.
`value`	`Native input value`	Native default	Submitted value for this option.

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 radio; 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.