Component field guide

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

LIVE COMPONENT

WelkDropDown

A labeled single-selection control. The default uses a styled native select; searchable uses an editable combobox and filtered list while retaining a native select for forms. Typing filters labels but does not commit a value. Use arrow keys and Enter to select; Escape dismisses the list.

Choose a hero

Usage

React / TSX

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

<WelkDropDown label="Choose a hero" searchable options={[
  { label: "Superman", value: "superman" },
  { label: "Batman", value: "batman" },
]} />

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

Variants and behavior

searchable=false: native select (default).
searchable=true: label-filtering combobox.

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.

Native select

Default native selection; the unavailable option cannot be chosen.

Native hero choice

Key propssearchable={false}

Searchable

Type to filter, then use arrows and Enter or select an option. Typing alone does not select.

Search for a role

Key propssearchable

Preselected

An initial uncontrolled value matches an option's value, not its label.

Starting role

Key propsdefaultValue="hero"

Disabled

A selected value remains visible without allowing edits.

Locked role

Key propsdisabled defaultValue="hero"

Usage notes and accessibility

Option values should be unique, stable strings. Use labels for human-readable names and disabled on choices that are currently unavailable.
Prefer the native select for short lists. searchable helps longer lists; filtering matches labels case-insensitively and does not change the selection until an option is committed.
In searchable mode use arrows to move, Enter to select, and Escape to dismiss. The hidden native select retains form submission and required validation.

Props

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

WelkDropDown prop reference
Prop	Type	Default	Description
`label`	`ReactNode`	Required	Visible, accessible control label.
`options`	`readonly WelkDropDownOption[]`	Required	Options: { value: string, label: string, disabled?: boolean }.
`value`	`string`	Uncontrolled	Controlled selection. Update it in onValueChange.
`defaultValue`	`string`	""	Initial value for uncontrolled use.
`onValueChange`	`(value: string) => void`	Unset	Called with the updated value; an empty string clears it.
`searchable`	`boolean`	false	Enables built-in case-insensitive filtering.
`placeholder`	`string`	"Select an option"	Text shown when no option is selected.
`name`	`string`	Unset	Name used when submitting a native form.
`id`	`string`	Generated	Control identifier; automatically linked to its label.
`disabled`	`boolean`	false	Prevents interaction.
`required`	`boolean`	false	Enables native required-field validation.
`className`	`string`	Unset	Additional CSS class on the component root.

Native props and refs

Forwards a native select ref. Only the listed props are supported, rather than arbitrary select attributes.

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.