Layout Components
Container-type layout components such as cards, grids, lists, tabs, collapse, dialogs, drawers, timelines, step bars, carousels, trees, menus, and more. Container components must be closed with [/type]. The left side shows the formatted TokUI DSL, the right side renders it in real time — click "Edit" to make changes on the fly.
Card card / Footer ft
card is a general-purpose content container. tt sets the title, tx writes the body text directly (self-closing mode), and the main content is filled by child nodes. ft acts as a child container of card, automatically placed at the bottom of the card as a footer.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
tt | Title | card | tt:用户信息 |
tx | Self-closing body text | card | tx:一段说明 |
hc | Title color (preset or color value) | card | hc:primary |
ht | Title decoration style | card | ht:underline |
w | Width | card | w:320 |
v | Variant | card | v:highlight |
v | Alignment | ft | v:right |
card variants: highlight (highlighted border), flat (flat, no shadow), bordered (outlined), center / right (title alignment). ht title decorations: fill (tinted fill), accent (left color bar), underline (underline), dot (leading dot), pill (tinted pill). fill/pill use a soft "10% tinted background + accent text" scheme; custom hc colors are tinted the same way automatically. ft variants: left / center / right.
Grid row / col
Responsive layout based on a 12-column grid system. row is the container row, col is the column, and span specifies the column width (1-12).
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
v | Alignment | row | v:center |
span | Column width (1-12) | col | span:4 |
row variants: left / center / right (horizontal alignment), inline (inline layout).
List list / item
List container. list is unordered (ul) by default; t:ol switches it to an ordered list (ol). item is a list item (<li> semantics) — text is written inside the tag, child list can be nested, and plain hides the marker.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
t | List type | list | t:ol |
plain | Remove marker/number | list | plain |
tx | Item text | item | tx:第一项 |
Tabs tabs / tab
tabs wraps multiple tab children. tt is each tab's navigation title, switched with pure CSS. Supports left/right arrow keyboard navigation.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
tt | Tab title | tab | tt:详情 |
Tab-switch callback: once
tabsdeclareson:"change:h", user tab switches report{index, title}; programmaticupdswitches do not fire it.
Accordion accordion / Collapse collapse
accordion wraps multiple collapse panels, each independently collapsible. tt sets the title; open expands by default.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
tt | Title | collapse | tt:第一章 |
open | Expand by default | collapse | open |
id | Identifier | collapse | id:sec1 |
Dialog dialog
Built on the native <dialog> element, with a backdrop + centered modal. Esc / click backdrop / close button all dismiss it.
| Prop | Meaning | Example |
|---|---|---|
tt | Title | tt:确认操作 |
id | Identifier (the trigger button's data-target points to it) | id:myDialog |
clk | Handler name | clk:openDialog |
Triggered by a button: the trigger button uses
clk:openDialog data-target:"<the dialog's id>", and the matching[dialog id:...]must carry the same id. Clicking calls the built-inopenDialoghandler, which finds the dialog by id and callsshowModal(). Cancel/confirm buttons inside useclk:closeDialogto dismiss the enclosing dialog (no id needed).
Close callback: once
on:"close:h"is declared, user close paths (Esc / backdrop / ✕) are reported with detail{}; programmatic[upd id:x act:close]is not reported (loop prevention).
Drawer drawer
A panel that slides in from the side. pos controls the direction; w sets the width for left/right drawers and h sets the height for top/bottom drawers. Esc / backdrop / close button all dismiss it.
| Prop | Meaning | Example |
|---|---|---|
tt | Title | tt:筛选条件 |
pos | Position (left/right/top/bottom, default right) | pos:left |
w | Width (left/right drawers, default 360px) | w:420 |
h | Height (top/bottom drawers, default 300px) | h:260 |
id | Identifier (the trigger button's data-target points to it) | id:myDrawer |
clk | Handler name | clk:openDrawer |
pos variants: left / right / top / bottom.
Triggered by a button: the trigger button uses
clk:openDrawer data-target:"<the drawer's id>", and the matching[drawer id:...]must carry the same id. Clicking calls the built-inopenDrawerhandler, which finds the drawer by id and adds thetokui-drawer--openclass to slide it in. Cancel/confirm buttons inside useclk:closeDrawerto dismiss the enclosing drawer.
Close callback: once
on:"close:h"is declared, user close paths (Esc / backdrop / ✕) are reported with detail{}; programmatic[upd id:x act:close]is not reported (loop prevention).
Timeline timeline / ti
timeline is the container; ti is a single record. tm sets the timestamp, tt the title, t the status color (primary/success/warning/error/info). The body text goes inside the tag.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
v | Layout (h/alternate/card) | timeline | v:alternate |
tm | Timestamp | ti | tm:2026-06-01 |
tt | Title | ti | tt:提交申请 |
t | Status color | ti | t:success |
timeline variants: h / horizontal (horizontal), alternate / alt (alternating left/right), card (card style).
Steps steps / step
A horizontal flow indicator. v sets the current step (1-based), vd:vertical switches to a vertical layout, and s:sm reduces the size. A step child can use status:error to mark an error state.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
v | Current step (1-based) | steps | v:2 |
vd | Direction (horizontal/vertical) | steps | vd:vertical |
s | Size | steps | s:sm |
tt | Step title | step | tt:填写信息 |
status | Per-step status | step | status:error |
Clickable steps: once
stepsdeclareson:"change:h", steps become clickable and a click reports{index, title}.
Carousel carousel / carousel-item
carousel is the container; children are carousel-item (or plain img). Children may also be written as [item] — inside carousel it renders as a slide (same name as [item] in list/desc, disambiguated by parent; item and carousel-item are equivalent and can be mixed). auto sets the autoplay interval (in milliseconds). Supports left/right arrows, indicator dots, dragging, and left/right keyboard navigation. thumb switches to a thumbnail legend below (replaces dots; click to jump smoothly). Sizing: w width, h height (plain numbers are px; %/vw/rem also accepted), or ratio aspect ratio (e.g. 16:9 / 4:3 / 1); when h or ratio is set, slides fill the height and images are cropped with object-fit:cover; h takes precedence over ratio.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
auto | Autoplay interval (ms) | carousel | auto:3000 |
id | Identifier | carousel | id:myCarousel |
thumb | Show thumbnail legend (replaces dots) | carousel | thumb |
w | Width (plain number → px, or %/vw/rem) | carousel | w:480 / w:100% |
h | Height (px; overrides ratio) | carousel | h:240 |
ratio | Aspect ratio (16:9 / 4:3 / 1) | carousel | ratio:16:9 |
s | Image URL | carousel-item / item | s:https://... |
tt | Slide title | carousel-item / item | tt:第一张 |
tx | Slide description | carousel-item / item | tx:说明文字 |
Switch reporting: once
on:"change:h"is declared, manual switches (arrows / dots / drag / keyboard) report{index}; autoplay does not fire it.
Fixed size (h) / aspect ratio (ratio) / thumbnail legend (thumb):
Tree tree / tn
tree is the container; child nodes tn can be nested recursively. On tn, leaf marks a leaf node, open expands by default, chk selects, and dis disables. On tree, chk enables checkbox mode.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
l | Field label | tree | l:目录 |
clk | Select callback | tree | clk:onPick |
chk | Checkbox mode | tree | chk |
dis | Disable the whole tree | tree | dis |
v / tx | Value / display text | tn | tx:src |
leaf | Leaf node | tn | leaf |
open | Expand by default | tn | open |
chk / dis | Selected / disabled | tn | chk |
load | Lazy-load data handler | tn | load:loadChildren |
Select & check reporting: declare
on:"change:h"to report{value, id}when a node is selected; in checkbox mode (chk), declareon:"check:h"to report{value: checked values array}on checkbox changes.
Lazy loading (load): when a
tndeclaresload:data-handler, expanding the node for the first time callsfn({id, value})(returning an array of child-node objects or a Promise) with a loading state shown while pending; loaded nodes are never re-fetched, and returned children may carryloadthemselves for recursive lazy loading. Completion reports theloadevent{value, count}.
Menu menu / menu-item
menu is the container; menu-item is self-closing. v switches direction (vertical default / horizontal / inline), act sets the clk value of the active item, and bg/fc customize colors.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
v | Direction variant | menu | v:horizontal |
act | Active item clk | menu | act:goHome |
bg / fc | Background / text color | menu | bg:1f2937 |
tx | Text | menu-item | tx:首页 |
clk | Click handler | menu-item | clk:goHome |
i | Icon glyph | menu-item | i:🏠 |
dis | Disabled | menu-item | dis |
Activation callback & programmatic activation: once
menudeclareson:"change:h", changes of the active item report{value}(item identity resolves as id > v > text); the server can activate a menu item programmatically with[upd id:m act:activate v:identity].
Resizable Panel resizable
A two-pane layout with a draggable splitter. dir controls the direction; min/max/default constrain the first pane's size. The first child node goes into the first pane; the rest go into the second. Supports fine-tuning with arrow keys.
| Prop | Meaning | Example |
|---|---|---|
dir | Direction (h horizontal default / v vertical) | dir:v |
min | Minimum size (px) | min:120 |
max | Maximum size (px) | max:600 |
default | Initial size (px) | default:240 |
w | Overall width | w:100% |
Horizontal · Sidebar + Main — The most common IDE / admin layout: a fixed-width left pane that can be dragged wider, and a right pane that fills the rest.
Vertical · Editor + Terminal — dir:v splits top/bottom: code or preview above, logs or console below.
Nested · Three-pane Workspace — resizable nests: outer splits horizontally, the right pane splits vertically again, yielding three regions.
Tight Constraint · Floating Rail — When min is close to max, the first pane is nearly fixed with only fine-tuning room.
Scroll Area scroll-area
A content region with a fixed outer size and custom scrollbar styling. h/w set the viewport size; overflowing content scrolls.
| Prop | Meaning | Example |
|---|---|---|
h | Height | h:160 |
w | Width | w:100% |
id | Identifier | id:myScroll |
virtual | Virtual scrolling (uniform row-height mode) | virtual |
ih | Row height (px, default 36) | ih:40 |
Virtual scrolling & load-more:
virtualmounts only the visible window plus a buffer into the DOM (uniform row-height mode — not suitable for variable-height rows); scrolling past the 80% threshold near the bottom reports theloadmoreevent (on:"loadmore:h", detail{}) — handy for long lists and chat-history "load more".
Sidebar sidebar
sidebar is a container; children are sidebar-content (main content) and sidebar-footer (footer). collapsible enables the collapse button.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
w | Width (default 260) | sidebar | w:240 |
pos | Position (left/right) | sidebar | pos:left |
collapsible | Collapsible | sidebar | collapsible |
tt | Title / logo text | sidebar | tt:控制台 |
bg / fc | Background / text color | sidebar | bg:111827 |
Tooltip tooltip
A lightweight hover-revealed text tip. tt is the tip content, tx is the trigger text, and pos controls the direction. It pops up on mouse enter and dismisses on leave/blur/Esc.
| Prop | Meaning | Example |
|---|---|---|
tt | Tip text | tt:这是提示 |
tx | Trigger text | tx:悬停看我 |
pos | Direction (default top) | pos:bottom |
Variants: top / bottom / left / right.
Popover popover
A richer popup card than tooltip, supporting a title and arbitrary child content. trig switches the trigger mode (click default / hover), pos controls the direction, and w sets the panel width.
| Prop | Meaning | Example |
|---|---|---|
tx | Trigger text | tx:点击查看 |
tt | Title | tt:用户信息 |
pos | Direction (default top) | pos:bottom |
trig | Trigger mode | trig:hover |
w | Panel width | w:240 |
Hover Card hover-card
hover-card is a container; children are hover-trigger (trigger area) and hover-content (pop-up content). delay controls the show delay, pos controls the direction, and the content is positioned with position:fixed to avoid clipping.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
pos | Direction (default bottom) | hover-card | pos:right |
w | Pop-up width (px) | hover-card | w:280 |
delay | Show delay (ms, default 300) | hover-card | delay:200 |
Popconfirm popconfirm
A small confirmation popup with OK / Cancel buttons triggered on click. tt is the question text, tx the trigger button text, clk the confirm callback, t the confirm button type, and pos the direction.
| Prop | Meaning | Example |
|---|---|---|
tt | Question text | tt:确定删除吗？ |
tx | Trigger button text | tx:删除 |
clk | Confirm callback | clk:onConfirm |
t | Confirm button type (default primary) | t:danger |
pos | Direction (default top) | pos:right |
ok-text / cancel-text | Button text | ok-text:删除 |
Back to Top backtop
A back-to-top button that appears after a page or container scrolls past a threshold. t sets the threshold (default 200), container switches to in-container mode, and v sets the shape.
| Prop | Meaning | Example |
|---|---|---|
t | Visibility threshold (px, default 200) | t:300 |
v | Shape (circle / round / square) | v:round |
tx | Button text (default ↑) | tx:顶部 |
s | Size | s:lg |
container | In-container mode | container |
bottom / right | Distance from bottom / right (px) | bottom:40 |
backtopfloats in the bottom-right corner and is only visible after scrolling. The example below uses a callout to describe its behavior.
Command Palette command
command is a container; children are command-group (group, tt title), whose items use item (or command-item — equivalent; item recommended). Built-in fuzzy search, keyboard up/down selection, and Enter to confirm.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
ph | Search box placeholder | command | ph:搜索命令... |
clk | Select callback | command | clk:onCommand |
id | Identifier (the trigger button's data-target points to it) | command | id:cmdMain |
tt | Group title | command-group | tt:常用 |
tx | Display text | item / command-item | tx:新建文件 |
v | Search value (defaults to tx) | item / command-item | v:new file |
clk | Item callback | item / command-item | clk:cmdNew |
shortcut | Shortcut hint | item / command-item | shortcut:⌘N |
The palette is hidden by default and triggered by a button: the trigger uses
clk:openCommand data-target:"<the command's id>", and the matching[command id:...]carries the same id. Usehotkeyto opt intoCmd/Ctrl+K(only one hotkey instance per page). When an item is selected: the item-levelclkhandler receives{ value, text }; if thecommandroot also hasclk, a root-level callback fires with{ value, text, clk }(clk= the item's handler name). Clicking the panel backdrop / search box fires nothing.
Canvas Panel canvas
canvas is a container; children are canvas-content (content area). pos controls the dock direction, w the width, open expands it by default, and closable whether it can be closed.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
tt | Title (default Canvas) | canvas | tt:预览 |
pos | Position (left/right, default right) | canvas | pos:right |
w | Width (default 400) | canvas | w:360 |
open | Expand by default | canvas | open |
closable | Closable (default on) | canvas | closable |
tx | Self-closing body text | canvas | tx:简单内容 |
Anchor anchor
Dual mode. In-page section navigation for long documents: clicking an item smooth-scrolls to its target, and scroll-spy highlights the item closest to the top while scrolling. Target elements must carry an id (e.g. [h2 id:sec-a 第一章]).
| Prop | Meaning | Example |
|---|---|---|
opt | Anchor shorthand string target-id:title;... (double quotes required, atomic self-closing) | opt:"sec-a:第一章;sec-b:第二章" |
top | scroll-spy activation offset (px, defaults to 12) | top:20 |
v | Variant: horizontal mode | v:horizontal |
on | change reports {value} (target id) | on:"change:h" |
id | Element ID | id:pageAnchor |
Container mode with lk children (supports nested anchors):
| Prop | Meaning | Example |
|---|---|---|
h | Target element id (# prefix allowed) | h:sec-a |
tx | Display text | tx:第一章 |
d | Depth 1-3 (indented) | d:1 |
After a click activation, the spy won't steal the highlight back during smooth scrolling (900ms suppression window);
[upd id:x v:目标id]activates programmatically (silent).
Clicking calls
scrollIntoViewfor smooth scrolling. The server can highlight an item programmatically with[upd id:pageAnchor v:target-id](silent — not reported).
Affix affix
Container. Pins its content with position:fixed once scrolling crosses an offset (top or bottom), inserting a placeholder automatically to prevent layout jumps. Pin-state changes are reported via the change event.
| Prop | Meaning | Example |
|---|---|---|
top | Pin to top: offset (px) from the scroll container's top edge; defaults to top:0 | top:8 |
bottom | Pin to bottom: offset (px) from the container's bottom edge (mutually exclusive with top) | bottom:8 |
target | Explicit scroll container selector (auto-detects the nearest scrollable ancestor by default) | target:#list |
on | Pin-state change reports {fixed:true/false} | on:"change:h" |
Bottom semantics: while the element sits below the bottom line it stays pinned to the bottom, and it releases once scrolled past its original position (same as AntD
offsetBottom). The scroll listener attaches towindowin the capture phase, so nested scroll containers (chat panes,scroll-area) are all detected.
Masonry masonry
Container. A CSS-columns masonry layout: cols for a fixed column count or minw for auto columns (minimum item width — the column count adapts to the container width); gap sets the spacing. Children are balanced across columns automatically and streaming appends flow naturally. Zero JS layout computation; children get break-inside: avoid so they are never cut mid-block.
| Prop | Meaning | Example |
|---|---|---|
cols | Fixed column count (1-6, defaults to 2) | cols:3 |
minw | Auto-column mode: minimum item width (px, wins over cols) | minw:200 |
gap | Gap (px, defaults to 8) | gap:10 |
Tour tour / tour-step
The tour container wraps a series of tour-step markers (self-closing) that walk the user through page elements step by step. Keyboard: Esc closes, ←/→ switch steps. A step without tgt shows its panel centered.
| Prop | Meaning | Applies to | Example |
|---|---|---|---|
open | Auto-start once the container closes | tour | open |
mask | Backdrop mask (on by default; mask:false turns it off) | tour | mask:false |
id | Identifier (for targeted upd control) | tour | id:tour1 |
on | Event reporting (see below) | tour | on:"change:h,finish:h,close:h" |
tgt | Target element id (may include #) | tour-step | tgt:"#btn-a" |
tt | Step title | tour-step | tt:第一步 |
tx | Step description (or write body text) | tour-step | tx:说明文字 |
pos | Panel placement (top/bottom/left/right, default bottom) | tour-step | pos:bottom |
Events:
change(step switch, detail{index,target}) /finish(completed) /close(skip · ✕ · Esc). Programmatic control:[upd id:tour1 act:open](voptionally picks the starting step),[upd id:tour1 act:goto v:N],[upd id:tour1 act:close]— all silent, never reported.
Imperative Confirm modal.confirm
An imperative confirm dialog — a host-side JS API, not part of the DSL — invoked directly from page code. It returns a Promise<boolean>: true on confirm, false on cancel / Esc / backdrop click. The alias TokUI.confirm(opts) is equivalent.
const ok = await TokUI.modal.confirm({
tt: 'Confirm deletion',
tx: 'Are you sure you want to delete this record?',
t: 'danger', // OK button type: 'danger' | 'primary' (default)
'ok-text': 'Delete', // defaults to i18n common.ok
'cancel-text': 'Cancel', // defaults to i18n common.cancel
onOk() { /* callback alongside the Promise */ },
onCancel() {}
});| Option | Meaning | Default |
|---|---|---|
tt | Title | i18n modal.aria |
tx | Body text | none (body area not rendered) |
t | OK button type | primary |
ok-text / cancel-text | Button labels | i18n common.ok / common.cancel |
onOk / onCancel | Callbacks (alongside the Promise) | — |
The overlay's aria text also comes from i18n (
modal.aria), so multilingual sites need no manual handling.
When nesting container components deeply, close each container with
[/type]immediately after its content to avoid rendering glitches caused by misplaced implicit closing during streaming parsing.