Input Field

表单元素大全：文本输入、选择器、日期、上传、开关、单选、复选、图标/颜色选择器。

TextField

单行文本输入，3 色 × 5 状态 × 2 形状，支持左右图标与后缀。

Import

import {
  TextField, TextArea, SelectOption, Datepicker,
  Toggle, RadioButton, CheckboxControl, CheckboxWithLabel,
  MediaUpload, ProfileImgUpload, FileUpload,
  IconSelector, IconPicker, ColorPicker,
} from "@forge-ui/react";

Usage

最小可用：只传 placeholder。受控时用 value + onChange。

Error message

1<TextField placeholder="Placeholder text. . ." />
2<TextField state="filled" value="Filled text" />
3<TextField state="error" placeholder="Input" errorMessage="Error message" />

Colors

3 种 focus 色：purple / blue / black。

1<TextField color="purple" placeholder="Purple" />
2<TextField color="blue" placeholder="Blue" />
3<TextField color="black" placeholder="Black" />

States

5 种状态：idle / filled / focus / disabled / error。

Error message

1<TextField placeholder="Idle" />
2<TextField state="filled" value="Filled text" />
3<TextField state="focus" placeholder="Focus" />
4<TextField state="disabled" placeholder="Disabled" />
5<TextField state="error" placeholder="Input" errorMessage="Error message" />

With Icon / Suffix

iconLeft / iconRight 放搜索、筛选、清空图标；suffix 放单位或选择器。

1<TextField iconLeft={<MagniferLinear size={20} />} placeholder="Search. . ." />
2<TextField iconRight={<MagniferLinear size={20} />} placeholder="Input" />
3<TextField suffix="cm" placeholder="Input length" />

Shape

圆角矩形或胶囊，通过 shape 切换。

1<TextField shape="rounded" placeholder="Rounded" />
2<TextField shape="pill" placeholder="Pill" />

API

Attribute	Type	Default	Description
`value`	`string`	`—`	当前值（受控）。
`placeholder`	`string`	`—`	占位文字。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	focus 高亮色。
`shape`	`'rounded' \| 'pill'`	`'rounded'`	圆角形状。
`state`	`'idle' \| 'filled' \| 'focus' \| 'disabled' \| 'error'`	`'idle'`	展示态，用于静态截图或强制高亮。
`iconLeft`	`ReactNode`	`—`	左侧图标槽。
`iconRight`	`ReactNode`	`—`	右侧图标槽。
`suffix`	`ReactNode \| string`	`—`	后缀，可为字符串单位或 TextFieldSelectSuffix。
`errorMessage`	`string`	`—`	error 态下方的错误文案。

TextArea

多行文本输入，支持 label + headerAction，其余 props 与 TextField 对齐。

Usage

带 label 可充当 form field 的完整单元。

Bio

1<TextArea placeholder="Placeholder text. . ." />
2<TextArea label="Bio" placeholder="Tell us about yourself..." />

API

Attribute	Type	Default	Description
`value`	`string`	`—`	当前值。
`placeholder`	`string`	`—`	占位文字。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	focus 高亮色。
`state`	`'idle' \| 'filled' \| 'focus' \| 'disabled' \| 'error'`	`'idle'`	展示态。
`label`	`string`	`—`	顶部标签文字。
`headerAction`	`ReactNode`	`—`	标签右侧的动作插槽，常放 Link。
`errorMessage`	`string`	`—`	error 文案。

SelectOption

下拉选择，支持单选 / 多选（tag 展示）/ 图片选项三种类型。

Usage

通过 type 切换模式，value 为选中值。

Select. . .

Option 1

1<SelectOption options={options} />
2<SelectOption type="single" value="o1" options={options} />
3<SelectOption type="multiple" value={["a", "b"]} options={tagOptions} />

Shape

圆角矩形或胶囊。

Select. . .

1<SelectOption shape="rounded" options={options} />
2<SelectOption shape="pill" options={options} />

API

Attribute	Type	Default	Description
`options`	`{ label: string; value: string }[]`	`—`	下拉选项列表。
`type`	`'general' \| 'single' \| 'multiple' \| 'image'`	`'general'`	general / single 单选（行为一致）/ multiple 多选（tag 展示）/ image 图片选项。
`value`	`string \| string[]`	`—`	当前选中值，multiple 时为数组。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	高亮色。
`shape`	`'rounded' \| 'pill'`	`'rounded'`	圆角形状。
`bgVariant`	`'white' \| 'grey'`	`'white'`	背景色变体。
`state`	`'idle' \| 'focus' \| 'disabled' \| 'error'`	`'idle'`	展示态。

Datepicker

日期选择，支持单日与区间两种模式。

Usage

点击触发后弹出日历面板，支持 single / range 两种模式。

Select date

Date range

Select date

1<Datepicker label="Select date" />
2<Datepicker label="Date range" mode="range" />

API

Attribute	Type	Default	Description
`label`	`string`	`—`	顶部标签文字。
`mode`	`'single' \| 'range'`	`'single'`	单日或区间选择。
`value`	`Date`	`—`	single 模式的选中日期。
`rangeStart / rangeEnd`	`Date`	`—`	range 模式的起止日期。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	高亮色。
`onChange`	`(date: Date) => void`	`—`	single 模式选中回调。
`onRangeChange`	`(start: Date, end: Date \| null) => void`	`—`	range 模式：第一次点击 end 为 null，第二次给完整区间。

Selection Controls

Toggle / RadioButton / CheckboxControl / CheckboxWithLabel 四类轻量控件，统一 3 色主色。

Toggle

开关，size 支持 md / sm。

1<Toggle checked={on} onChange={setOn} />
2<Toggle checked={on} color="blue" />
3<Toggle checked={on} size="sm" />

Attribute	Type	Default	Description
`checked`	`boolean`	`false`	开关状态。
`onChange`	`(checked: boolean) => void`	`—`	切换回调。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	选中态主色。
`size`	`'md' \| 'sm'`	`'md'`	尺寸档位。
`disabled`	`boolean`	`false`	禁用态。

RadioButton

单选按钮，通常成组使用，父层管 value。

Option 1Option 2Option 3

1<RadioButton checked={value === "a"} onChange={() => setValue("a")} />
2<RadioButton checked={value === "b"} onChange={() => setValue("b")} color="blue" />

Attribute	Type	Default	Description
`checked`	`boolean`	`false`	选中状态。
`onChange`	`(checked: boolean) => void`	`—`	切换回调。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	选中态主色。
`disabled`	`boolean`	`false`	禁用态。

CheckboxControl

勾选框本体，不含 label。

1<CheckboxControl checked={on} onChange={setOn} />
2<CheckboxWithLabel label="I agree" checked={on} onChange={setOn} />

Attribute	Type	Default	Description
`checked`	`boolean`	`false`	选中状态。
`onChange`	`(checked: boolean) => void`	`—`	切换回调。
`color`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'black'`	`'purple'`	选中态主色（CheckboxColor，6 色）。

CheckboxWithLabel

勾选框 + 行内 label，支持 icon / avatar / dotColor 三种 leading。

I agree to the terms

1<CheckboxControl checked={on} onChange={setOn} />
2<CheckboxWithLabel label="I agree" checked={on} onChange={setOn} />

Attribute	Type	Default	Description
`checked`	`boolean`	`false`	选中状态。
`onChange`	`(checked: boolean) => void`	`—`	切换回调。
`label`	`string`	`—`	右侧文字。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	选中态主色。
`checkboxPosition`	`'left' \| 'right'`	`'left'`	勾选框相对于 label 的位置。
`icon`	`ReactNode`	`—`	label 前的小 icon。
`avatar`	`string`	`—`	label 前的圆形头像 URL。
`dotColor`	`string`	`—`	label 前的 dot 颜色（Tailwind bg-* class）。
`disabled`	`boolean`	`false`	禁用态。

Upload

三种上传区：MediaUpload 多图网格、ProfileImgUpload 头像单图、FileUpload 文件列表。

MediaUpload

多图上传，传 items 注入已上传缩略图。

Images

Drag and drop image here, or click add image

1<MediaUpload label="Images" />
2<ProfileImgUpload label="Avatar" />
3<FileUpload label="Attachments" />

Attribute	Type	Default	Description
`items`	`MediaItem[]`	`[]`	已上传图片数组（含 src / state / progress）。
`label`	`string`	`—`	组件上方标签。
`buttonLabel`	`string`	`'Add Image'`	添加按钮文案。
`message`	`string`	`'Drag and drop image here, or click add image'`	拖拽提示文案。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	按钮 / icon 主色。
`onUpload`	`(files: FileList) => void`	`—`	选择 / 拖入文件后回调。
`onRemove`	`(id: string) => void`	`—`	条目删除回调。

ProfileImgUpload

单张头像上传，src 为已有头像 URL。

Avatar

1<MediaUpload label="Images" />
2<ProfileImgUpload label="Avatar" />
3<FileUpload label="Attachments" />

Attribute	Type	Default	Description
`src`	`string`	`—`	已上传头像 URL；为空时显示占位。
`label`	`string`	`—`	组件上方标签。
`linkLabel`	`string`	`'Upload'`	上传链接文案。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	链接 + icon 主色。
`onUpload`	`(files: FileList) => void`	`—`	选择文件回调。

FileUpload

通用文件上传，files 数组带 progress / state / 失败重传。

Attachments

1<MediaUpload label="Images" />
2<ProfileImgUpload label="Avatar" />
3<FileUpload label="Attachments" />

Attribute	Type	Default	Description
`files`	`FileItem[]`	`[]`	已上传文件数组（含 name / size / state / progress）。
`label`	`string`	`—`	组件上方标签。
`buttonLabel`	`string`	`'Add File'`	添加按钮文案。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	按钮主色。
`onUpload`	`(files: FileList) => void`	`—`	选择 / 拖入文件后回调。
`onRemove`	`(id: string) => void`	`—`	条目删除回调。
`onRetry`	`(id: string) => void`	`—`	失败重传回调。

Pickers

ColorPicker / IconPicker / IconSelector —— 三类可视化选择器。

ColorPicker

固定色板，传 colors 自定义。

1<ColorPicker selectedIndex={0} />
2<IconPicker icons={iconList} selectedIndex={0} onChange={setIndex} />
3<IconSelector label="Icons" icons={iconList} selectedIndex={0} onChange={setIndex} />

Attribute	Type	Default	Description
`colors`	`string[]`	`default palette`	色板（每项为 Tailwind bg-* class）。
`selectedIndex`	`number`	`—`	当前选中下标。
`onChange`	`(index: number) => void`	`—`	切换回调。

IconPicker

紧凑图标网格，icons 传图标节点数组。

1<ColorPicker selectedIndex={0} />
2<IconPicker icons={iconList} selectedIndex={0} onChange={setIndex} />
3<IconSelector label="Icons" icons={iconList} selectedIndex={0} onChange={setIndex} />

Attribute	Type	Default	Description
`icons`	`ReactNode[]`	`—`	图标节点列表，用 solar-icon-set 实例。
`selectedIndex`	`number`	`—`	当前选中下标。
`onChange`	`(index: number) => void`	`—`	切换回调。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	选中态主色。

IconSelector

带 label 的完整卡片，点击 Select 弹出搜索 popover。

Icons

1<ColorPicker selectedIndex={0} />
2<IconPicker icons={iconList} selectedIndex={0} onChange={setIndex} />
3<IconSelector label="Icons" icons={iconList} selectedIndex={0} onChange={setIndex} />

Attribute	Type	Default	Description
`icons`	`ReactNode[]`	`—`	图标节点列表。
`selectedIndex`	`number`	`—`	当前选中下标。
`onChange`	`(index: number) => void`	`—`	切换回调。
`label`	`string`	`—`	组件上方标签。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	选中态主色。
`searchPlaceholder`	`string`	`'Search icon. . .'`	popover 内搜索框占位。

看所有变体 →