Basic Components

The most frequently used display components: headings, text, buttons, tags, callouts, progress, statistics, loaders, Markdown, syntax highlighting, and more. In each example, the left panel shows the formatted and highlighted TokUI DSL, while the right panel renders it live; click "Edit" to modify it on the fly.

Headings h1 ~ h6

Six-level headings, self-closing. tx is the text (optional — you can write the content inline), v controls alignment and decoration, and bg / fc set the colors.

Prop	Meaning	Example
tx	Text content (or write content inline)	[h1 标题]
v	Variant (alignment / decoration, comma-combinable)	v:underline、v:"center,ribbon"
bg	Background / accent color: theme name (primary/success/warning/danger/dark/light) or 6-digit hex (no #)	bg:success、bg:722ed1
fc	Text color (same values as bg)	fc:danger
id	Element ID (targeted by upd/del/ins)	id:title1

Variants: left / center / right (alignment), ribbon, underline, badge / pill. The decorative variants (ribbon/badge/pill/underline) share a "tinted background + accent text" scheme: bg: sets the accent color and the 10% tint background and soft border are derived automatically, adapting to light and dark themes. Without a decorative variant, bg paints a solid full-width background.

Six levels side by side:

1[h1 一级标题]

2[h2 二级标题]

3[h3 三级标题]

4[h4 四级标题]

5[h5 五级标题]

6[h6 六级标题]

Loading TokUI…

TokUI DSL · code ↔ render

Alignment variants:

1[h3 v:left 左对齐（默认）]

2[h3 v:center 居中对齐]

3[h3 v:right 右对齐]

Loading TokUI…

TokUI DSL · code ↔ render

Decorative variants (recolor with bg):

1[h2 v:ribbon 缎带标题]

2[h2 v:ribbon bg:success 成功色缎带]

3[h2 v:underline 下划线标题]

4[h2 v:underline bg:warning 警告色下划线]

5[h3 v:badge 徽标标题]

6[h3 v:badge bg:danger 危险色徽标]

7[h3 v:pill 胶囊标题]

8[h3 v:pill bg:722ed1 自定义色胶囊]

Loading TokUI…

TokUI DSL · code ↔ render

Solid bg + fc text color, and combining alignment with decoration:

1[h3 bg:1677ff fc:ffffff 实底白字标题]

2[h3 v:"center,underline" bg:danger 居中 + 危险色下划线]

Loading TokUI…

TokUI DSL · code ↔ render

Paragraph p

Body paragraph, dual-mode (same trap as card's tx self-closing): body text present → leaf self-closing; no body text → container collecting children. v controls alignment and weight.

• Leaf mode [p text] / [p v:bold text]: text is the body; may hold inline children (a/tag/b/strong/em/mark/spin/sub/sup/code); auto-closes on a block sibling.
• Container mode [p]...[/p]: use when placing block children like btn/form/card; must close with [/p].
• Body text shaped like word:value (e.g. Q:/A:) is parsed as an attribute (no-space → body empty; with-space → prefix vanishes) — use a full-width ： or drop the colon (see DSL syntax).

Variants: left / center / right (alignment), muted, bold, sm / lg (font size).

1[p 这是默认段落，用于承载正文内容。]

2[p v:muted 弱化段落，用于次要信息或辅助说明。]

3[p v:bold 加粗段落，用于强调重点。]

4[p v:sm 小字号段落，常用于脚注。]

5[p v:lg 大字号段落，用于引语。]

Loading TokUI…

TokUI DSL · code ↔ render

1[p Leaf mode allows [a u:# tx:inline link]

2and

3[b inline bold]

4.]

5[p]

6[btn tx:block btn in container clk:ok]

7[btn tx:reset clk:cancel]

8[/p]

9[p Q：full-width colon counts as body.]

Loading TokUI…

TokUI DSL · code ↔ render

Link a

Hyperlink, self-closing. u is the URL, tx is the text, and target controls how it opens.

Prop	Meaning	Example
u	URL	u:https://tokui.jboltai.com
tx	Text	tx:官网
target	Open behavior	target:_blank
v	Variant	v:underline

Variants: muted / danger / success / underline.

1[p]

2[a u:# tx:默认链接]

3·

4[a u:# tx:下划线链接 v:underline]

5·

6[a u:# tx:弱化链接 v:muted]

7·

8[a u:# tx:危险链接 v:danger]

9·

10[a u:# tx:成功链接 v:success]

11[/p]

12[p]

13[a u:https://github.com/jboltai/tokui tx:新窗口打开 GitHub target:_blank v:underline]

14[/p]

Loading TokUI…

TokUI DSL · code ↔ render

Divider hr / dv

hr is a plain horizontal rule (self-closing). dv is a divider with text and styling (self-closing).

Prop	Meaning	Applies to
tx	Divider text	dv
v	Line style / direction	dv
bg	Color	dv

dv variants: dashed / dotted (line style), sm / md / lg (spacing), vert (vertical), plain.

1[p 上方内容]

2[hr]

3[p 下方内容]

4[dv tx:章节分隔]

5[dv v:dashed]

6[dv tx:垂直场景 v:vert]

Loading TokUI…

TokUI DSL · code ↔ render

Image img / Gallery imgs

img renders a single image with click-to-zoom lightbox preview. imgs is a container that lays out multiple images in an adaptive grid (up to 3×3).

Prop	Meaning	Example
s	Image URL	s:https://...
alt	Alt text	alt:封面
w / h	Width / Height	w:120
v	Variant	v:avatar

img variants: avatar, rounded, bordered.

1[row]

2 [col span:4]

3 [img s:https://assets.vdata.chat/jboltai/aiimg/logo_60.png v:avatar w:72 alt:头像]

4 [/col]

5 [col span:4]

6 [img s:https://picsum.photos/seed/tokui1/200/120 v:rounded w:200 alt:圆角图]

7 [/col]

8 [col span:4]

9 [img s:https://picsum.photos/seed/tokui2/200/120 v:bordered w:200 alt:边框图]

10 [/col]

11[/row]

Loading TokUI…

TokUI DSL · code ↔ render

imgs multiple images: pass comma-separated URLs via s, and they are arranged into a 1–9 cell grid automatically.

1[imgs s:"https://picsum.photos/seed/a/200,https://picsum.photos/seed/b/200,https://picsum.photos/seed/c/200,https://picsum.photos/seed/d/200"]

Loading TokUI…

TokUI DSL · code ↔ render

Preview Group preview-group

Container. Binds a set of img children into a shared preview session: clicking any image opens the lightbox with the whole group's src list (the lightbox supports zoom / rotate / flip / counter / prev-next navigation). Images that arrive later during streaming join the group automatically.

Prop	Meaning	Example
id	Element ID	id:gallery

Difference from imgs: imgs is a shorthand grid layout, while preview-group expresses the explicit semantics of "one group of images sharing a preview session" — the images keep their normal layout inside.

1[preview-group]

2[img s:https://picsum.photos/seed/a/200]

3[img s:https://picsum.photos/seed/b/200]

4[/preview-group]

Loading TokUI…

TokUI DSL · code ↔ render

Kbd kbd

Self-closing inline element. Keycap-styled text for shortcut/operation documentation; works as an inline child of p mixed with text.

Variants: sm / lg.

1[p 全局搜索：[kbd Ctrl]

2[kbd K]

3；取消：

4[kbd Esc]

5]

Loading TokUI…

TokUI DSL · code ↔ render

Float Button float-button

Container. Pins a group of children (btn / backtop, etc.) to a viewport corner; children are automatically rounded into floating action buttons.

Prop	Meaning	Example
pos	Placement: right-bottom (default) / right-top / left-bottom / left-top	pos:left-top
offset	Offset from the viewport edge (px, defaults to 24)	offset:80

1[float-button pos:right-bottom offset:80]

2[btn tx:💬]

3[/float-button]

Loading TokUI…

TokUI DSL · code ↔ render

Button btn / Button Group btngroup

btn is self-closing and is the most commonly used interactive component. btngroup is a container that wraps a set of buttons.

Prop	Meaning	Example
tx	Text	tx:提交
clk	Click handler name	clk:onSave
sub	Form submit handler name	sub:onSubmit
dis	Disabled	dis
w	Width	w:200
bg / fc	Background / text color	bg:4f46e5
t	Native type	t:reset
v	Variant (type / size / shape)	v:"primary,pill"
icon	SVG icon name (inherits button color)	icon:view
i	emoji / character icon	i:🔍
l	icon-only label (a11y + hover tooltip)	l:删除

Type variants: primary / danger / success / warning / ghost. Size / shape variants: sm / lg / pill (rounded) / square (sharp corners) / block (full-width).

1[btngroup]

2 [btn tx:主要 v:primary]

3 [btn tx:成功 v:success]

4 [btn tx:警告 v:warning]

5 [btn tx:危险 v:danger]

6 [btn tx:幽灵 v:ghost]

7[/btngroup]

8[p v:muted]

9[btn tx:小 v:"primary,sm"]

10[btn tx:默认 v:primary]

11[btn tx:大 v:"primary,lg"]

12[btn tx:块级 v:"primary,block" tx:占满整行]

13[/p]

14[p v:muted]

15[btn tx:圆角 v:"primary,pill"]

16[btn tx:直角 v:"primary,square"]

17[btn tx:禁用 v:primary dis]

18[/p]

Loading TokUI…

TokUI DSL · code ↔ render

Icon Buttons

Two icon sources, shared by [btn] and the table action column:

• icon:NAME — built-in SVG (Lucide-style stroke, stroke=currentColor inherits button color)
• i:GLYPH — emoji / character (rendered verbatim)

Without tx it becomes an icon-only button: auto-compacted, l: provides the aria-label + hover tooltip.

Icon names: view edit delete add copy download upload refresh check close search setting warn info lock unlock more save export filter sort star link menu

1[btngroup]

2 [btn icon:view tx:详情 t:primary clk:toast]

3 [btn icon:edit tx:编辑 t:warning clk:toast]

4 [btn icon:delete l:删除 t:danger clk:toast]

5 [btn i:🔍 tx:搜索 clk:toast]

6[/btngroup]

7[p v:muted]

8First three are icon+text (colored), third is icon-only (hover shows "删除"), last is emoji.

9[/p]

Loading TokUI…

TokUI DSL · code ↔ render

Handlers referenced by clk: / sub: must be pre-registered via TokUI.registerHandler(name, fn); the DSL itself never carries executable code.

Tag tag

Labels and categorization, self-closing.

Prop	Meaning	Example
tx	Text	tx:新功能
t	Type / color	t:danger
s	Size	s:sm
round	Rounded	round
closable	Closable	closable
bordered	Outlined	bordered

1[tag tx:新功能 v:primary round]

2[tag tx:热门 t:danger]

3[tag tx:推荐 t:success bordered]

4[tag tx:默认]

5[tag tx:可关闭 t:warning closable]

6[tag tx:小尺寸 s:sm]

Loading TokUI…

TokUI DSL · code ↔ render

Callout callout

Informational prompt with an icon, self-closing.

Prop	Meaning	Example
t	Type	t:success
tt	Title	tt:操作成功
tx	Body	tx:已保存

Types: info / success / warning / error / tip.

1[callout t:info tt:信息提示]

2这是一条普通信息提示。

3[/callout]

4[callout t:success tt:操作成功]

5数据已成功保存。

6[/callout]

7[callout t:warning tt:请注意]

8该操作不可撤销。

9[/callout]

10[callout t:error tt:发生错误]

11请求失败，请稍后重试。

12[/callout]

Loading TokUI…

TokUI DSL · code ↔ render

Barcode barcode

Code128 Set B pure-SVG barcode (zero-dependency). Suited for tracking/order/serial numbers — any variable-length alphanumeric data. Scanners auto-detect.

Prop	Meaning	Example
tx	data to encode (also shown as human-readable text below)	tx:"SF1026883749"
l / tt	top label	l:"运单号"
s	size sm/md/lg (default md; accepts small/medium/large)	s:medium

Visible ASCII only (32–126). Module ratio is preserved (preserveAspectRatio meet) so scaling stays scannable.

1[barcode tx:"SF1026883749" l:"运单号" s:medium]

2[row]

3 [col span:6]

4 [barcode tx:"PO-2026-0042" l:"采购单" s:sm]

5 [/col]

6 [col span:6]

7 [barcode tx:"SN88001122334455" l:"序列号" s:lg]

8 [/col]

9[/row]

Loading TokUI…

TokUI DSL · code ↔ render

QR Code qrcode

Pure-SVG QR code (matrix generation vendored from qrcode-generator by Arase, MIT; this repo stays zero-npm-dependency). Supports URL / text / UTF-8.

Prop	Meaning	Example
tx	data to encode (URL/text, UTF-8)	tx:"https://tokui.jboltai.com"
l / tt	label below	l:"Scan to visit"
s	size sm/md/lg (default md)	s:md
ec	error correction L(7%)/M(15%)/Q(25%)/H(30%), default M	ec:H

Includes a 4-module quiet zone + white background, shape-rendering=crispEdges and preserveAspectRatio=meet to keep modules proportional and scannable when scaled. Higher EC tolerates more damage but is denser.

1[qrcode tx:"https://tokui.jboltai.com" l:"TokUI 官网" s:md ec:M]

2[row]

3 [col span:6]

4 [qrcode tx:"https://github.com/jboltai/tokui" l:"GitHub" s:sm]

5 [/col]

6 [col span:6]

7 [qrcode tx:"WIFI:S:TokUI-Guest;T:WPA;P:welcome;;" l:"Wi-Fi" s:lg ec:H]

8 [/col]

9[/row]

Loading TokUI…

TokUI DSL · code ↔ render

Status Dot dot

Status indicator, self-closing.

Prop	Meaning	Example
t	Status type	t:success
tx	Text	tx:运行中
s	Size	s:lg
pulse	Pulse animation	pulse

1[dot t:success tx:在线 pulse]

2[dot t:warning tx:忙碌]

3[dot t:danger tx:离线]

4[dot tx:默认 s:lg]

Loading TokUI…

TokUI DSL · code ↔ render

Badge badge / badge-box

badge is a numeric / dot badge (self-closing) that wraps its children. badge-box is a container that attaches a corner badge to its children.

Prop	Meaning	Applies to
count	Number (parseInt truncates decimals; use tx for versions/decimals)	both
dot	Dot	both
tx	Text badge	both (badge-box also accepts legacy label; tx preferred)
t	Status color (default/primary/success/warning/error)	both
overflow	Overflow display (e.g. 99+)	both
pill	Pill (rounded)	badge
size	Size (sm/lg)	badge
title	Hover tooltip	badge

1[badge count:5]

2[btn tx:消息 v:ghost]

3[/badge]

4[badge count:99]

5[btn tx:通知 v:ghost]

6[/badge]

7[badge dot]

8[btn tx:待办 v:ghost]

9[/badge]

Loading TokUI…

TokUI DSL · code ↔ render

Two ways to badge a heading (h3 is self-closing; never nest [h3 text [badge]]):

• Inline pill (a label beside the title, e.g. a version/status): wrap h3 + badge in row v:inline (flex mode). Must use v:inline — the default row is a 12-col grid that squeezes the heading into wrap.
• Corner badge (top-right marker, e.g. unread/dot): wrap h3 in badge-box.

1[row v:inline]

2 [h3 SaaS Pro]

3 [badge tx:v2.4 pill t:primary]

4[/row]

Loading TokUI…

TokUI DSL · code ↔ render

1[badge-box tx:v2.4 t:primary]

2 [h3 SaaS Pro]

3[/badge-box]

Loading TokUI…

TokUI DSL · code ↔ render

Progress progress

Self-closing. v is the current value (0–100).

Prop	Meaning	Example
v	Current value	v:60
l	Label	l:下载中
t	Shape	t:circle
stripe	Striped	stripe
status	Status color	status:success

Shapes: line (default) / circle (ring) / span (inline).

1[progress v:30 l:下载中]

2[progress v:65 l:处理中 stripe]

3[progress v:100 status:success l:完成]

4[row]

5 [col span:4]

6 [progress t:circle v:75]

7 [/col]

8[/row]

Loading TokUI…

TokUI DSL · code ↔ render

Statistic stat

Data display card, self-closing.

Prop	Meaning	Example
tt	Label	tt:今日访问
v	Value	v:12345
pre / suf	Prefix / suffix	suf:%
trend	Trend	trend:up
dec	Decimal places	dec:1
anim	Number animation	anim

1[row]

2 [col span:6]

3 [stat tt:今日访问 v:12834 trend:up]

4 [/col]

5 [col span:6]

6 [stat tt:转化率 v:3.2 suf:% trend:down dec:1]

7 [/col]

8[/row]

9[row]

10 [col span:6]

11 [stat tt:营收 pre:¥ v:98210 trend:up]

12 [/col]

13 [col span:6]

14 [stat tt:退款 v:12 suf:笔 trend:down]

15 [/col]

16[/row]

Loading TokUI…

TokUI DSL · code ↔ render

Countdown countdown

Self-closing. Provide target as a target timestamp or dur as the countdown duration in seconds.

Prop	Meaning	Example
target	Target time	target:2026-12-31
dur	Duration in seconds	dur:3600
fmt	Format	fmt:dd天hh:mm:ss
tx	End text	tx:已结束

1[callout t:info tt:秒杀倒计时]

2[countdown dur:86400 fmt:hh:mm:ss tx:活动已结束]

3[/callout]

Loading TokUI…

TokUI DSL · code ↔ render

Loader spin / Skeleton skeleton / Shimmer shimmer

spin is a loading indicator, skeleton is a skeleton screen, and shimmer is a shimmering placeholder. All are self-closing.

Prop	Meaning	Applies to
t	Type	all three
s	Size	spin
tx	Text	spin
rows	Number of rows	skeleton / shimmer

1[row]

2 [col span:4]

3 [spin t:spinner tx:加载中…]

4 [/col]

5 [col span:4]

6 [spin t:dots]

7 [/col]

8 [col span:4]

9 [spin t:pulse s:lg]

10 [/col]

11[/row]

12[skeleton t:card rows:3]

13[shimmer t:text rows:2]

Loading TokUI…

TokUI DSL · code ↔ render

Empty State empty / Result Page result

empty is a no-data placeholder and result is an operation result page. Both are self-closing.

Prop	Meaning	Applies to
tx	Description	both
icon	Icon	empty
t	Type	result
tt	Title	result

result types: success / error / warning / info.

1[row]

2 [col span:6]

3 [card tt:空状态]

4 [empty tx:暂无数据]

5 [/card]

6 [/col]

7 [col span:6]

8 [card tt:结果页]

9 [result t:success tt:提交成功 tx:我们将在3个工作日内审核]

10 [/card]

11 [/col]

12[/row]

Loading TokUI…

TokUI DSL · code ↔ render

Copy copy

One-click copy button, self-closing. id points to the target element to copy, or it copies the tx text.

Prop	Meaning	Example
id	Target element ID	id:codeBlock
tx	Button text	tx:复制
tt	Success toast	tt:已复制

1[p v:muted v:bold id:copyTarget 这段文字可以被一键复制。]

2[copy id:copyTarget tx:复制这段 tt:已复制到剪贴板]

Loading TokUI…

TokUI DSL · code ↔ render

Markdown md

Markdown rendering container. Supports common syntax: headings, lists, blockquotes, code, tables, links, and more.

Optional plugin enhancement: ```mermaid fences and $$formula$$ / $formula$ are enhanced automatically when the host loads the window.mermaid / window.katex globals; without the plugins they fall back to source display (zero-dependency behavior is unaffected, and currency amounts like $5 $6 are not mis-parsed).

1[md]

2 ## Markdown 渲染支持 **加粗**、*斜体*、`行内代码`、

3 [链接]

4 (#)。- 无序列表项一- 无序列表项二> 引用块文字。

5[/md]

Loading TokUI…

TokUI DSL · code ↔ render

Formula katex / Diagram mermaid

Standalone component aliases for the md plugin pipeline — declared directly instead of writing md text:

• [katex]O(n) = \sum_{i=1}^{n} t_i[/katex] — container, block formula
• [katex f:"E = mc^2"] — f: attribute, inline formula
• [mermaid]flowchart LR\n A --> B[/mermaid] — container, diagram source (raw content; inner [ is not parsed)

Without katex/mermaid loaded they fall back to source / code block. katex content is exempt from raw escape decoding — write LaTeX commands like \nabla/\times/\to verbatim.

1[katex f:"E = mc^2"]

Loading TokUI…

TokUI DSL · code ↔ render

Code Block code

Syntax-highlighted code container. lang specifies the language; the zero-dependency built-in highlighter covers 11 languages: js / ts / python / java / go / rust / sql / html / css / json / bash.

Prop	Meaning	Example
lang	Language	lang:js
tx	Title (file name)	tx:app.js

1[code lang:js]

2 function greet(name) {\n return `Hello, ${name}!`;\n}\nconsole.log(greet("TokUI"));

3[/code]

Loading TokUI…

TokUI DSL · code ↔ render

1[code lang:python]

2 def fib(n):\n a, b = 0, 1\n for _ in range(n):\n a, b = b, a + b\n return a\n\nprint(fib(10))

3[/code]

Loading TokUI…

TokUI DSL · code ↔ render

Inside code content, newlines are encoded as \n. See the DSL syntax reference for the full prop table.