Skip to content

Form Components

Form containers, various input controls and selectors. Each example shows the formatted, highlighted TokUI DSL on the left and the live render on the right; click "Edit" to modify it instantly. Every form control's label renders a required asterisk when req is set.

Form Container form

Wraps a group of form controls. On submit, triggers the sub: handler or the native act submission.

PropMeaningExample
actSubmit URLact:/api/save
mtdSubmit methodmtd:post
subSubmit handler namesub:onSubmit
clkGeneric event handler nameclk:onFormClick

The handler referenced by sub: must be pre-registered via TokUI.registerHandler(name, fn); on a btn, use sub:xxx to trigger form submission.

1[card tt:登录表单]
2 [form act:/api/login mtd:post sub:onLogin]
3 [input l:账号 ph:"请输入账号" req]
4 [pwd l:密码 ph:"请输入密码" req]
5 [ft]
6 [btn tx:登录 v:primary sub:onLogin]
7 [btn tx:重置 v:ghost t:reset]
8 [/ft]
9 [/form]
10[/card]
Loading TokUI…
TokUI DSL · code ↔ render

Value-Change Reporting (change event)

Form controls report user value changes in real time to a pre-registered handler via on:"change:handler" (double quotes required) — the "user → AI" interaction loop:

tokui
[input n:city l:City on:"change:onCityChange"]
[switch l:Notifications n:notify on:"change:onNotifyChange"]
  • Input debounce: input / pwd / textarea / numinput report 300ms after typing stops; override the milliseconds with db: (e.g. db:500).
  • Fire on change: select / radio / checkbox / switch / slider / rate / picker / transfer / cascader / datepicker family / input-tag report immediately when the value changes.
  • upload: reports change when files are selected / removed, with detail {value: filename array, name}.
  • detail shape: handler signature (detail, event, element), with detail = {value, name}.
  • Unified outlet: every interaction also goes to new TokUI({ onEvent })'s onEvent('component', { type, id, event, detail }) — the host can listen to everything without any on: declaration.

For the full event list see DSL Syntax · Interaction event reporting.

DSL Validation Rules

input / pwd / textarea / select support declarative validation via rule: + msg:, enforced uniformly on submit (all sub / t:submit paths). Failures block submission, mark the field red with a hint, and focus the first invalid field:

tokui
[input n:email l:"Email" rule:"required|email"]
[input n:code l:"Code" rule:"required|len:6" msg:"Please enter the 6-digit code"]
[select n:city l:"City" rule:"required" opt:"bj:Beijing;sh:Shanghai"]
  • Rules are pipe-separated and short-circuit in order: required email url number len:N (exact length) min:N max:N (character count) re:regex.
  • Empty values skip non-required rules (HTML5 semantics: empty + not required = valid).
  • msg: customizes the error message (built-in i18n text by default); unknown rule names / invalid regexes are skipped with a console.warn.
  • Combined with live: real-time validation on blur, with instant re-check while typing in the error state.
  • req on select writes the native required attribute (except multi-select, where the semantics don't fit).

Input input

Single-line text input, self-closing. l for label, ph for placeholder, t for native type, val for initial value.

PropMeaningExample
lLabell:姓名
phPlaceholder hintph:"请输入姓名"
tNative input typet:email
nField namen:username
valDefault valueval:Tom
idElement IDid:username
wWidthw:240
hintHint texthint:6~16 个字符
searchSearch stylesearch
rule / msgDSL validation rules / custom error message (see DSL Validation Rules)`rule:"required
sugInput-suggestion data-source handlersug:onSuggest
req / dis / roRequired / Disabled / Read-onlyreq

Variants: error / success (validation states), sm / lg (sizes), underline (underline style), pill (rounded).

1[input l:姓名 ph:"请输入姓名" req]
2[input l:邮箱 t:email ph:name@example.com]
3[input l:带默认值 val:张三]
4[input l:搜索框 ph:"输入关键词搜索" search]
5[input l:禁用态 ph:不可编辑 dis]
6[input l:错误状态 v:error ph:校验失败]
Loading TokUI…
TokUI DSL · code ↔ render

Input suggestions (sug): sug:data-source-handler enables a suggestion dropdown — fn({value}) returns an array or a Promise (items are strings or {v, tx}); navigate with ↑↓ / Enter / Esc, and selecting fires the change report.

Password pwd

Password input with show/hide toggle, self-closing. Same props as input, plus toggle to control whether plain text can be revealed.

PropMeaningExample
lLabell:密码
phPlaceholder hintph:"至少 6 位"
toggleShow/hide toggle buttontoggle
req / disRequired / Disabledreq
vVariant (same as input)v:error
1[pwd l:登录密码 ph:"请输入密码" req toggle]
2[pwd l:支付密码 ph:6 位数字 req]
3[pwd l:禁用态 ph:不可编辑 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Textarea textarea

Multi-line text input container. rows for initial row count, maxlen for max character count, auto for auto-growing height.

PropMeaningExample
lLabell:描述
phPlaceholder hintph:"请输入描述"
rowsInitial rowsrows:4
maxrowsMax rows (auto mode)maxrows:8
maxlenMax character countmaxlen:200
autoAuto-grow heightauto
txDefault contenttx:"默认文本"
req / dis / roRequired / Disabled / Read-onlyreq
1[textarea l:默认值自闭合 tx:"热爱前端开发,擅长组件设计与性能优化。" maxlen:120]
2[textarea l:只读协议自闭合 ro tx:"本服务仅供学习,禁止商用。"]
3[textarea l:空容器嵌套 ph:"请简单介绍自己" rows:3]
4[/textarea]
5[textarea l:自适应高度 auto rows:2 maxrows:6 ph:"内容增多会自动撑开"]
6[/textarea]
7[textarea l:带内容嵌套 rows:4 ph:"请输入反馈"]
8 希望增加暗色主题与多语言支持。
9[/textarea]
Loading TokUI…
TokUI DSL · code ↔ render

select is a container; opt are child option nodes. multi for multi-select, req for required.

PropMeaningApplies to
lLabelselect
phPlaceholder hintselect
multiMulti-selectselect
nField nameselect
reqRequiredselect
vVariantselect
txOption textopt
vOption valueopt
chkDefault selectedopt

select variants: error / success.

1[select l:单选部门 ph:"请选择"]
2 [opt 技术部]
3 [opt 市场部 chk]
4 [opt 运营部]
5[/select]
6[select l:多选技能 multi]
7 [opt React chk]
8 [opt Vue chk]
9 [opt Node]
10[/select]
11[select l:必选城市 req ph:"请选择城市"]
12 [opt 北京]
13 [opt 上海]
14[/select]
Loading TokUI…
TokUI DSL · code ↔ render

Radio Group radio

radio is a container; opt are child option nodes. Options sharing the same n are mutually exclusive. Two forms: container ([opt] children) or opt:"..." shorthand (self-closing, no [/radio] needed).

PropMeaningApplies to
lGroup labelradio
nField name (shared by group, submission key)radio
idGroup IDradio
vinline (label beside control) / vertical (options stacked, left-aligned)radio
optShorthand option string opt:"v:label;v:label" (self-closing form)radio
txOption textopt
vOption valueopt
chkDefault selectedopt
1[radio l:性别 n:gender]
2 [opt v:1 tx:]
3 [opt v:2 tx: chk]
4[/radio]
5[radio l:配送方式(简写) n:deliver opt:"1:快递;2:自提;3:同城配送"]
6[radio l:渠道(竖排) n:ch v:vertical opt:"1:官方网站;2:手机APP;3:门店"]
Loading TokUI…
TokUI DSL · code ↔ render

Checkbox checkbox

Three modes (auto-detected by presence of opt / multi):

ModeDetectionSyntaxSubmitted value
Single booleanno opt, no multi (self-closing)[checkbox l:同意协议 n:agree chk]boolean (checked = agree present)
Shorthand multihas opt (self-closing)[checkbox n:tag l:标签 opt:"1:A;2:B;3:C"]data.tag = array
Container multihas multi (container)[checkbox n:tag l:标签 multi][opt v:1 tx:A chk][/checkbox]data.tag = array
PropMeaningApplies to
lLabelcheckbox
nField name (multi-select submission key)checkbox
optShorthand option string (self-closing multi)checkbox
multiMarks container multi mode (needs [/checkbox])checkbox
vinline/verticalcheckbox
chkDefault checked / selectedcheckbox / opt
disDisabledcheckbox

Multi-select submission uses native FormData; same-n values auto-aggregate into an array (e.g. checking A and C → data.tag = ["1","3"]). Single-boolean and shorthand-multi are self-closing — do NOT write [/checkbox]; only multi container-multi needs [/checkbox].

Submit-button placement (get this wrong → no data): put it inside the form [form id:F sub:H]...[btn tx:Submit clk:H][/form] (clk auto-collects the owning form); OR outside the form but with explicit form:FORM_ID binding [btn tx:Submit form:F clk:H]. A button outside the form with no form:ID → handler receives null.

1[checkbox l:我已阅读并同意服务条款 n:agree chk]
2[checkbox l:订阅每周精选 n:weekly]
3[checkbox l:禁用且勾选 n:x chk dis]
4[checkbox n:tag l:标签(简写多选) opt:"1:篮球;2:足球;3:羽毛球"]
5[checkbox n:f l:功能(竖排) v:vertical opt:"1:即时通讯;2:会议;3:日历;4:云盘"]
Loading TokUI…
TokUI DSL · code ↔ render

Switch switch

Self-closing. chk to turn on, clk for the toggle callback.

PropMeaningExample
lLabell:邮件通知
chkDefault onchk
disDisableddis
clkToggle handler nameclk:onToggle
nField namen:notify
vValuev:1
idElement IDid:notify

Variants: sm / lg.

1[switch l:接收邮件通知 chk]
2[switch l:免打扰模式]
3[switch l:夜间静音 clk:onNight]
4[switch l:小尺寸 chk v:sm]
5[switch l:大尺寸 chk v:lg]
Loading TokUI…
TokUI DSL · code ↔ render

Slider slider

Self-closing. min/max/step for range and step, v for current value.

PropMeaningExample
lLabell:音量
minMinimum valuemin:0
maxMaximum valuemax:100
stepStepstep:5
vCurrent valuev:60
disDisableddis
clkDrag callbackclk:onSlide
nField namen:volume
idElement IDid:volume
rangeDual-thumb range moderange
marksTick labels (value:label, comma-separated)marks:"0:免费,50:标准"

Variants: sm / lg.

1[slider l:音量 v:60 min:0 max:100]
2[slider l:亮度 step:5 v:75]
3[slider l:不透明度 v:30 clk:onOpacity]
4[slider l:禁用 v:50 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Range & marks: range selects an interval with two thumbs (v:"20,60"), and change reports {value: [min, max]}; marks:"0:免费,50:标准,100:旗舰" renders tick labels.

Rate rate

Self-closing. max for max star count, v for current rating, clk for the select callback.

PropMeaningExample
lLabell:评分
vCurrent valuev:4
maxMax starsmax:5
clkSelect callbackclk:onRate
disRead-only / disableddis
txCaption texttx:很好
halfHalf-star selection (0.5 steps; clicking the same value again clears it)half
1[rate l:商品评分 v:4 max:5]
2[rate l:服务评分 v:0 max:5 clk:onRate]
3[rate l:只读评分 v:5 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Number Input numinput

Self-closing. Number input with increment/decrement buttons; min/max/step constrain the range.

PropMeaningExample
lLabell:数量
vCurrent valuev:1
minMinimum valuemin:1
maxMaximum valuemax:99
stepStepstep:1
disDisableddis
nField namen:qty
idElement IDid:qty
1[numinput l:购买数量 v:1 min:1 max:99 step:1]
2[numinput l:时长(小时) v:8 min:0 max:24 step:0.5]
3[numinput l:禁用 v:5 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Button Group btngroup

Container that wraps a set of btns. In form scenarios, commonly used as a multi-button action area (for primary button usage see Basic Components).

PropMeaningExample
idGroup IDid:actions
vVariantv:vertical

Variants: vertical (vertical layout), pill (rounded group).

1[btngroup]
2 [btn tx:保存 v:primary sub:onSave]
3 [btn tx:取消 v:ghost]
4[/btngroup]
5[btngroup v:vertical]
6 [btn tx:上传 v:primary]
7 [btn tx:下载]
8 [btn tx:删除 v:danger]
9[/btngroup]
Loading TokUI…
TokUI DSL · code ↔ render

Picker picker

Container; a richer selection panel than select (with search / multiple columns). multi for multi-select, dis for disabled.

PropMeaningExample
lLabell:城市
phPlaceholder hintph:"请选择"
multiMulti-selectmulti
disDisableddis
nField namen:city
vValuev:bj
idElement IDid:city

Variants: error / success.

1[picker l:所在城市 ph:"请选择城市"]
2[/picker]
3[picker l:标签(多选) multi ph:"请选择标签"]
4[/picker]
5[picker l:禁用态 ph:不可选择 dis]
6[/picker]
Loading TokUI…
TokUI DSL · code ↔ render

Cascader cascader

Container; a multi-level selector that expands level by level (e.g. province/city/district). clk for the select callback.

PropMeaningExample
lLabell:地区
phPlaceholder hintph:"请选择"
disDisableddis
clkSelect callbackclk:onPick
vValuev:"北京-朝阳"
nField namen:region
idElement IDid:region

Variants: error / success.

1[cascader l:所在地区 ph:"请选择省/市/区"]
2[/cascader]
3[cascader l:商品分类 clk:onCategory]
4[/cascader]
Loading TokUI…
TokUI DSL · code ↔ render

Upload upload

Self-closing. accept restricts file types, multi for multiple files, max for maximum count.

PropMeaningExample
lLabell:附件
phPlaceholder hintph:"点击或拖拽上传"
acceptAllowed typesaccept:"image/*"
multiMultiple filesmulti
maxMax countmax:5
disDisableddis
clkUpload callbackclk:onUpload
nField namen:file
idElement IDid:file
uUpload URL (http(s) / relative paths only; enables auto-transfer)u:/api/upload
mtdUpload methodmtd:post

Variants: sm / lg.

Transfer layer: with u: set, selected files are automatically uploaded one by one via XHR; each file item shows a progress bar / success ✓ / failure ✗+retry state, and reports the progress {file, percent} / success {file, response} / error {file, error} events. Without u:, selection stays frontend-only (only the change event).

1[upload l:头像 accept:"image/*" ph:"点击上传头像"]
2[upload l:多文件上传 multi max:5 ph:"支持最多 5 个文件"]
3[upload l:禁用上传 dis]
Loading TokUI…
TokUI DSL · code ↔ render

The server can push [upd id:file act:clear] to clear the selected-file list.

Date Picker datepicker

Self-closing. fmt for date format, v for default value, clk for the select callback.

PropMeaningExample
lLabell:出生日期
phPlaceholder hintph:"请选择日期"
fmtDate formatfmt:yyyy-MM-dd
vDefault valuev:2026-06-20
clkSelect callbackclk:onDate
disDisableddis
nField namen:birthday
idElement IDid:birthday
rangeRange mode (two clicks pick start and end)range
1[datepicker l:出生日期 ph:"请选择日期" fmt:yyyy-MM-dd]
2[datepicker l:默认值示例 v:2026-06-20]
3[datepicker l:禁用态 ph:不可选择 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Range mode: with range, two clicks pick the start and end dates; the value format is YYYY-MM-DD ~ YYYY-MM-DD.

Time Picker timepicker

Self-closing. fmt for time format, v for default value.

PropMeaningExample
lLabell:开始时间
phPlaceholder hintph:"请选择时间"
fmtTime formatfmt:HH:mm
vDefault valuev:09:30
clkSelect callbackclk:onTime
disDisableddis
nField namen:time
idElement IDid:time
1[timepicker l:开始时间 ph:"请选择时间" fmt:HH:mm]
2[timepicker l:默认值 v:09:30]
3[timepicker l:禁用态 ph:不可选择 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Datetime Picker datetimepicker

Self-closing. Combined date + time picker; fmt for custom format.

PropMeaningExample
lLabell:预约时间
phPlaceholder hintph:"请选择日期时间"
fmtFormatfmt:"yyyy-MM-dd HH:mm"
vDefault valuev:"2026-06-20 09:30"
clkSelect callbackclk:onDateTime
disDisableddis
nField namen:dt
idElement IDid:dt
1[datetimepicker l:预约时间 ph:"请选择日期时间" fmt:"yyyy-MM-dd HH:mm"]
2[datetimepicker l:默认值 v:"2026-06-20 09:30"]
3[datetimepicker l:禁用态 ph:不可选择 dis]
Loading TokUI…
TokUI DSL · code ↔ render

Transfer transfer

Container; a two-column mutually exclusive multi-select mover. tt/tt2 for the two column titles, clk for the move callback.

PropMeaningExample
lLabell:分配角色
ttLeft column titlett:未选
tt2Right column titlett2:已选
clkMove callbackclk:onTransfer
hFixed height (inner scroll)h:240 / h:40vh
mhMax height (overrides default 320px)mh:200
disDisableddis
nField namen:roles
idElement IDid:roles

Variants: sm (max 260px) / lg (max 400px). Default max-height 320px; overflowing lists scroll inside (scrollbar transparent by default, grey semi-transparent on hover).

1[transfer l:角色分配 tt:待分配 tt2:已分配 clk:onTransfer]
2 [opt v:admin tx:系统管理员]
3 [opt v:editor tx:内容编辑 chk]
4 [opt v:viewer tx:只读访客]
5 [opt v:auditor tx:审计员 chk]
6 [opt v:dev tx:开发者]
7[/transfer]
Loading TokUI…
TokUI DSL · code ↔ render

h fixed height and mh max height examples:

1[transfer l:固定高度 h:160 tt: tt2:]
2 [opt v:1 tx:选项一]
3 [opt v:2 tx:选项二 chk]
4 [opt v:3 tx:选项三]
5 [opt v:4 tx:选项四]
6 [opt v:5 tx:选项五 chk]
7 [opt v:6 tx:选项六]
8[/transfer]
9[transfer l:最大高度 mh:140 tt:候选 tt2:已选]
10 [opt v:a tx:短列表A]
11 [opt v:b tx:短列表B chk]
12[/transfer]
Loading TokUI…
TokUI DSL · code ↔ render

Input Tag input-tag

Press Enter to add a tag, click a tag's × to remove it. tags for initial tags, max for maximum count. Self-closing when tags is present; otherwise close with [/input-tag].

PropMeaningExample
lLabell:标签
phPlaceholder hintph:"输入后回车添加"
nField namen:tags
maxMax countmax:8
tagsInitial tags (comma-separated)tags:"JS,Python"
disDisableddis
1[input-tag l:技术栈 ph:"输入后回车添加" max:8 tags:"JavaScript,Python,Go"]
2[input-tag l:极简自闭合 tags:"React,Vue"]
3[input-tag l:空容器 ph:"无初始标签,手动添加"]
4[/input-tag]
5[input-tag l:禁用态 tags:"只读模式" dis]
Loading TokUI…
TokUI DSL · code ↔ render

Segmented segmented

A lightweight single-choice switcher (the form-control counterpart of tabs). Two forms: the opt shorthand (atomic self-closing) or container mode with opt children (icons, per-option disabled).

PropMeaningExample
optShorthand option string v:label;... (double quotes required)opt:"list:列表;grid:宫格"
vCurrently selected value (combinable with shape variants)v:"sm,grid"
nField namen:view
lLabell:视图
disDisable the whole groupdis
onchange reports {value,name}on:"change:h"
idElement IDid:view

Variants: sm / lg / block (full width) / pill (rounded) / vertical.

Container-mode opt children (fine-grained per-option control):

PropMeaningExample
vOption valuev:grid
txDisplay texttx:宫格
iIcon character (emoji/symbol)i:📊
chkChecked by default (v match wins)chk
disDisable this optiondis

The server can switch programmatically with [upd id:view v:grid]; a form reset restores the initial value.

1[segmented l:视图 v:grid opt:"list:列表;grid:宫格;table:表格"]
2[segmented v:"pill,day" opt:"day:日;week:周;month:月"]
3[segmented n:perm v:read]
4[opt v:read tx:只读]
5[opt v:write tx:读写]
6[opt v:admin tx:管理员 dis]
7[/segmented]
Loading TokUI…
TokUI DSL · code ↔ render

Color Picker color-picker

Self-closing. The picker panel combines a saturation/brightness pick area, a hue slider, a hex input, preset swatches, and a clear action. presets configures the preset colors. When opened, the panel portals to document.body with fixed positioning so it is never clipped by a parent container's overflow; it repositions to follow the anchor on scroll and closes on outside click or Escape.

PropMeaningExample
vInitial color (#rrggbb, defaults to #1677ff)v:#1677ff
presetsPreset colors (comma-separated hex)presets:"#f5222d,#fa8c16"
nField namen:color
lLabell:主题色
disDisableddis
onchange reports {value,name}on:"change:h"
idElement IDid:color

The server can recolor programmatically with [upd id:color v:#hex] and re-enable with [upd id:color dis:false]; a form reset restores the initial value.

1[color-picker l:主题色 v:#1677ff presets:"#f5222d,#fa8c16,#52c41a,#1677ff,#722ed1"]
Loading TokUI…
TokUI DSL · code ↔ render

Editable editable

Self-closing inline element. The text carries a dashed underline marking it as editable; clicking enters the editing state: Enter/blur commits, Escape restores (no report).

PropMeaningExample
tx / vInitial texttx:小木屋
phPlaceholder when emptyph:点击填写
nField namen:nick
disDisableddis
onCommit (value changed) reports {value,name}on:"change:h"
idElement IDid:ed1

The server can rewrite programmatically with [upd id:ed1 tx:新值] (silent) and unlock with [upd id:ed1 dis:false].

1[p]
2昵称:
3[editable tx:小木屋 n:nick]
4[/p]
5[p]
6签名:
7[editable ph:点击填写 n:sign]
8[/p]
9[p]
10锁定项:
11[editable tx:不可编辑 dis]
12[/p]
Loading TokUI…
TokUI DSL · code ↔ render

For the full DSL syntax (prop shorthands, variant whitelist, streaming render constraints, etc.), see DSL Syntax.