UI Input, Pane, and Render Types

Types with Fields

Each type below has its own table of fields.

InputProps

The props of Input, the text field of every surface. It has an address, optional texts, and the closures that a change and a submit run. A leaf. One line, or several with rows. While it has focus every printable key reaches it, and Esc returns them. A change and Enter raise ui.input.

Field	Status	What it is for	Type and limits
key	Documented: An official docs page names this item.	The address of the element: e.element at ui.input, what a matcher names.	Type: string.
label	Documented: An official docs page names this item.	Text drawn before the field.	Type: string. Optional.
placeholder	Documented: An official docs page names this item.	Text drawn dim in an empty field.	Type: string. Optional.
value	Documented: An official docs page names this item.	The text that the field holds when drawn. The typing of the person replaces it until the hook draws another.	Type: string. Optional.
submitLabel	Documented: An official docs page names this item.	What Enter does, in a word or two, drawn beside the field while it has focus (send). Defaults to submit.	Type: string. Optional.
rows	Documented: An official docs page names this item.	How many lines tall the field is: a whole number of at least 1. From 2 it holds several lines, as the <textarea rows> of the DOM. Defaults to 1.	Type: number. Optional. Drawn this tall. A longer text scrolls inside. Enter submits. Up and Down walk its rows, then go to the next element.
autoFocus	Documented: An official docs page names this item.	The focus ring of the site starts here when the site takes the keyboard, instead of on nothing, as the autofocus of the DOM. Enter acts on it at once.	Type: true. Optional. A pane opened with focus takes it. Of several in one site, the first drawn wins. A ring that the person has moved stays where it is.
onInput	Documented: An official docs page names this item.	Runs on every change of the text, in the own environment of the plugin: the bottom of a ui.input chain of kind change.	Type: (value: string, e: UiInputArgument) => void. Optional. The text is whole, with its lines joined by \n.
onSubmit	Documented: An official docs page names this item.	Runs on Enter with the text, in the own environment of the plugin: the bottom of a ui.input chain of kind submit. No model turn unless it asks one.	Type: (value: string, e: UiInputArgument) => void. The text is whole, with newlines kept and nothing trimmed.

LinkProps

The props of Link, a hyperlink that every surface draws. It is an OSC 8 span on the terminal (else its text, then the URL in dim) and an anchor on desktop. It is an inline element. Its children are the text. With no children, the label is the text. With neither, the URL is the text.

Field	Status	What it is for	Type and limits
href	Documented: An official docs page names this item.	Where the link goes, as written: any scheme, host and port, at most 2048 characters once the engine percent-encodes what a terminal acts on.	Type: string. A blank value draws plain text. On a remote surface only an https: URL is a link. A click opens what the surface opens.
label	Documented: An official docs page names this item.	The text drawn when the element has no children. If both are absent, the URL itself is the text.	Type: string. Optional.

MarkdownLeafProps

What a Markdown carries across the boundary: its address, text, dimness and which links it answers. onLinkPress stays behind, and a press goes instead.

Field	Status	What it is for	Type and limits
key	Documented: An official docs page names this item.	The address of the element: what e.element carries and what a matcher names. Present whenever the element carries a press.	Type: string. Optional.
text	Documented: An official docs page names this item.	The markdown drawn, checked as the string of a Text is.	Type: string.
dimColor	Documented: An official docs page names this item.	The whole block dim, as the dimColor of Text. If absent, it draws as false.	Type: boolean. Optional.
pressableLinks	Documented: An official docs page names this item.	Which links a press belongs to, by href as written. If absent, with a press, every link drawn. The engine compares it with the pressed target only.	Type: readonly string[]. Optional.

MarkdownProps

The props of Markdown, a block of markdown that every surface draws as it draws the text of an assistant reply. It has its own renderer, links, tables, fences. A leaf with no children. With onLinkPress a press on a link raises ui.press addressed to key.

Field	Status	What it is for	Type and limits
key	Documented: An official docs page names this item.	The address of the element: e.element at ui.press, what a matcher names. Required with onLinkPress, because a press needs one. Else optional.	Type: string. Optional.
text	Documented: An official docs page names this item.	The markdown drawn, as an assistant reply would write it. A <context> block, hidden in the own text of a reply, is drawn here as written.	Type: string. One drawing draws 100000 characters in all. A link that is not https:, http:, or file: draws as text.
dimColor	Documented: An official docs page names this item.	The whole block dim, as the dimColor of Text: a thought, an aside.	Type: boolean. Optional.
onLinkPress	Documented: An official docs page names this item.	What a press on a link in text runs, in the own environment of the plugin: the bottom of a ui.press chain whose e.link names the link.	Type: (link: PressedLink, e: UiPressArgument) => void. Optional. Called on a plain single click where the surface reports clicks. Ctrl, alt, or cmd click opens the link as before.
pressableLinks	Documented: An official docs page names this item.	Which links in text a press belongs to, by href as the markdown writes it. If absent, every link drawn. Only with onLinkPress.	Type: readonly string[]. Optional. A link left out keeps the own behavior of the surface. At most 256 entries of at most 2048 characters.

NotifyOptions

Options of $.ui.notify. Used by $.ui.notify.

Field	Status	What it is for	Type and limits
title	Documented: An official docs page names this item.	What heads the notification, sent as the mod gives it. The engine puts no name of its own beside it. If left out or empty, the name of the plugin.	Type: string. Optional.

OnScreen

The part of a transcript message that is on the screen of the surface that drew it. It is units first to last of the of of the message, counted from its start. It says which rows of a site are on screen. The terminal counts rows. Other surfaces use their own unit, so compare first / of there.

Field	Status	What it is for	Type and limits
first	Documented: An official docs page names this item.	The unit inside the viewport, from 0. On the terminal, it is 7 when the top seven rows of the message are scrolled away.	Type: number.
last	Documented: An official docs page names this item.	The unit inside the viewport, inclusive, at least first.	Type: number.
of	Documented: An official docs page names this item.	The whole extent of the message in the same unit, as laid out (a hook tree taller than the engine tree counts its own rows). It is more than last.	Type: number. The numbers of one surface say nothing of another. What the phone displays the terminal may not. Each ui.render carries the numbers of its own surface.

PaneCloseInput

The input of ui.close: the pane that closes and why (PaneCloseOrigin). Closing an id that is not open does nothing. Used by ui.close.

Field	Status	What it is for	Type and limits
id	Documented: An official docs page names this item.	What $.ui.open named the pane. Pinned: next(e) passes it on.	Type: string.
origin	Documented: An official docs page names this item.	Who closes it. The engine sets it. A hook that answers without next keeps the pane open on plugin and person, never on unload.	Type: PaneCloseOrigin.

PaneCloseOrigin

Why a pane closes, as the engine stamped it at ui.close. unload drops a pane that nothing draws any more, before the hooks hear of it. next(e) passes the origin on as received.

Field	Status	What it is for	Type and limits
kind	Documented: An official docs page names this item.	plugin is the $.ui.close of a plugin. person is the close mark or close key of the person. unload is the engine itself.	Type: 'plugin' | 'person' | 'unload'.

PaneOpenArgs

The argument of $.ui.open. It has which pane, its title, whether it asks for the keyboard of the person, its dialog manners, and its size: rows inline, columns docked. An open that answers the input of the person is placed at any width. An open that the plugin makes alone waits below 144 columns. Used by $.ui.open, ui.open.

Field	Status	What it is for	Type and limits
id	Documented: An official docs page names this item.	Names the pane: 1-64 of letters, digits, _ and -. One pane for each id. Opening an open id delivers the new title, never a second instance.	Type: string. Pinned at the hooks: next(e) passes it on. The title and focus rewrite.
title	Documented: An official docs page names this item.	The tab of the pane while more than one pane is open (with one, no title is drawn), and the title that its hook sees. It is the id when omitted.	Type: string. Optional. An unpaired surrogate half (a .slice() through an emoji) is drawn as U+FFFD. The engine refuses a control character.
focus	Documented: An official docs page names this item.	A request, not a grant. The surface focuses (and raises) the pane only while the prompt has the keys over an empty composer.	Type: true. Optional. An element of the band, a pane that the person holds, text in the composer, a dialog or a survey each refuse it. The pane opens without the keyboard.
closeOnEscape	Documented: An official docs page names this item.	While the pane holds the keyboard, the key that hands it back (Escape) also closes it, as the close of the person does: ui.close, origin person.	Type: true. Optional. Escape at an idle, empty prompt closes the pane. A hook may refuse the close. Each open sets it anew.
holdToasts	Documented: An official docs page names this item.	While the pane is the one displayed, the surface holds every transient toast. That includes the $.ui.toast of each other plugin, the own toasts of the engine, and those of this plugin.	Type: true. Optional. Toasts wait while the pane is open. Use it for a dialog that the person answers and leaves. Each open sets it anew.
backgroundColor	Documented: An official docs page names this item.	What the surface paints under the pane's body while it is the one shown, as a Box takes it: a theme key, a raw color, or "transparent".	Type: Color. Optional. "transparent" paints nothing, so what lies behind the pane shows through. A color stops at the body. Left out, the surface's own look stands. Anything else is refused. Each open sets it anew, and a ui.open hook may drop it. A request, not a grant: a surface with no counterpart for a theme key keeps its own look. Since 2.1.311.
rows	Documented: An official docs page names this item.	The body rows that the content of the pane wants while seated inline above the prompt. It opens that tall, up to what the layout spares, not a third.	Type: number. Optional. A request, not a grant. A size that the person dragged wins. The dock ignores it. A positive whole number.
columns	Documented: An official docs page names this item.	The body columns the pane's content wants while docked beside a fullscreen transcript: the dock opens that wide, at most 45% of the terminal's columns and at least 24. Each open sets it anew.	Type: number. Optional. A request, not a grant. A width the person dragged or keyed wins, under the same ceiling. Since 2.1.305 the dock stays within 45% of the terminal's width, also for a requested or chosen width and a width kept from a wider terminal, with a floor of 24 columns. The cap is also at most the terminal's width minus 60 columns. The dock is hidden below 110 columns, so the floor and the cap never clash (the program; v2.1.305 release). The inline block ignores it. A positive whole number.

PressedLink

The link that a press landed on. It is one that a Markdown drew, pressed where the surface reports presses (a plain click in the fullscreen terminal). It holds what the surface knows of the cell pressed, not which occurrence. Two links written with one target read the same here.

Field	Status	What it is for	Type and limits
href	Documented: An official docs page names this item.	The target of the link as the surface drew it. For an https: link, it is the href as the markdown wrote it.	Type: string.

RasterBlitArgs

A $.ui.blit argument that repaints one of the mounted Rasters of the caller. columns and rows, when given, must be the mounted size. A resize is a redraw ($.ui.invalidate("ui.render")), not a blit.

Field	Status	What it is for	Type and limits
requestId	Documented: An official docs page names this item.	The site that the Raster is drawn in, by the requestId that this plugin draws it under. It is the id of one of its panes, the tool_use_id of a tool row, or the id of the band.	Type: string.
key	Documented: An official docs page names this item.	The key of the Raster in that drawing.	Type: string.
cells	Documented: An official docs page names this item.	The new cells, encoded as the cells of the element are (RasterProps), for the mounted columns \* rows.	Type: string.
columns	Documented: An official docs page names this item.	The width that the cells are laid out for. The engine refuses it unless it is the width of the mounted Raster. If absent, the mounted width.	Type: number. Optional.
rows	Documented: An official docs page names this item.	The height that the cells are laid out for. The engine refuses it unless it is the height of the mounted Raster. If absent, the mounted height.	Type: number. Optional.

RasterProps

The props of Raster, the cell-grid leaf of the terminal surface. It is a fixed box of cells, each a glyph, a foreground and a background, packed in cells. A leaf with no children, hover, or onPress. $.ui.blit repaints it in place. Terminal only. The palette holds 1024 color pairs.

Field	Status	What it is for	Type and limits
key	Documented: An official docs page names this item.	The address of the element within the drawing: what $.ui.blit names to repaint it. Unique among the Rasters of one tree.	Type: string.
columns	Documented: An official docs page names this item.	How many terminal columns wide, 1 to 512. The site clips what its body cannot show.	Type: number.
rows	Documented: An official docs page names this item.	How many terminal rows tall, 1 to 256.	Type: number.
cells	Documented: An official docs page names this item.	Every cell, row-major: standard padded base64 of columns \* rows little-endian u32 triplets [codePoint, foreground, background].	Type: string. Each cell is a code point plus colors. A code point is one printable width-1 BMP character. A color is 0x00RRGGBB, or 0x01000000 for the terminal default.

RenderElement

What a render hook returns, and what next(e) resolves to: a plain-data tree of elements (a Box or Text is a StyledElement), with strings as children. Union of the element types. Props are an allowed subset of the Ink Box and Text props. A tree with any other prop fails as a whole. Used by ui.render.

Field	Status	What it is for	Type and limits
type	Documented: An official docs page names this item.	A button, on every surface: [ label ] on the terminal, a native button on a desktop. A press raises ui.press (e.element is the key).	Type: 'Button'. Built by <Button>. The onPress closure stays in the own environment of the plugin under press.handle.
props	Documented: An official docs page names this item.	The props of the element, typed object.	Type: object.
press	Documented: An official docs page names this item.	Where the handler lives: the plugin whose hook drew the element, and the handle that its environment keeps the onPress closure under.	Type: object. The runtime stamps the plugin as the tree leaves that hook.
hover	Documented: An official docs page names this item.	Label style overrides (the Text set). The surface applies them while the nearest keyed Box, or the group that scope names, is hovered. Plain data.	Type: TextHoverProps. Optional.
children	Documented: An official docs page names this item.	What is drawn in the place of the label, all of it one pressable: strings and Text (a chip, a dim part). The engine refuses any other element.	Type: RenderNode[]. Optional. Absent for a Button of a label alone, drawn as it always was.
type	Documented: An official docs page names this item.	A text field on every surface, of one line or of rows. A change and Enter raise ui.input (e.element, e.kind, and e.value as the text).	Type: 'Input'. Built by <Input>. The onInput and onSubmit closures stay in the environment of the plugin. A leaf with no children.
props	Documented: An official docs page names this item.	The props of the element, typed object.	Type: object.
press	Documented: An official docs page names this item.	Where the handlers live: the plugin whose hook drew the element, and the handle that its environment keeps the closures under.	Type: object. The runtime stamps the plugin as the tree leaves that hook.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A one-of-several picker on every surface. A pick raises ui.select (e.element is the key, e.value is the value of the option).	Type: 'Select'. Built by <Select> or the table's t.Select. The onSelect closure stays in the own environment of the plugin under press.handle, held as the closure of a Button is. A leaf: no children.
props	Documented: An official docs page names this item.	The props of the element, typed object.	Type: object.
press	Documented: An official docs page names this item.	Where the handler lives: the plugin whose hook drew the element, and the handle that its environment keeps the closure under.	Type: object. The runtime stamps the plugin as the tree leaves that hook.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A hyperlink that every surface draws. It is an OSC 8 span on the terminal (its text, then the URL in dim where unsupported) and an anchor on desktop.	Type: 'Link'. Inline. Its children are the text: strings and inline elements. With absent children, the label is the text. With both absent, the URL is the text. href is drawn as written. If it is no string, the text draws plain.
props	Documented: An official docs page names this item.	The props of the element, typed LinkProps.	Type: LinkProps.
children	Documented: An official docs page names this item.	The child nodes.	Type: RenderNode[]. Optional.
type	Documented: An official docs page names this item.	Source code that every surface draws with the highlighter of the engine, with tokens coloured by language. Under format: 'diff', unified-diff hunks.	Type: 'Code'. A leaf. A dim gutter numbers the lines from startLine. A diff has two gutters and add and remove backgrounds.
props	Documented: An official docs page names this item.	The props of the element, typed CodeProps.	Type: CodeProps.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A block of markdown that every surface draws as it draws the text of an assistant reply. It has its own renderer, theme, hyperlinks and highlighting.	Type: 'Markdown'. Built by <Markdown>. A leaf. Without a press its links open as the surface opens links.
props	Documented: An official docs page names this item.	The props of the element, typed MarkdownLeafProps.	Type: MarkdownLeafProps.
part	Documented: An official docs page names this item.	Whose key it is: the engine sets it on a keyed element as the tree leaves its hook, as on a Box (new in 2.1.307).	Type: PluginStamp. Optional.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A Markdown whose plugin answers the links that it drew (onLinkPress). A press on one raises ui.press with e.link, and the surface opens none.	Type: 'Markdown'.
props	Documented: An official docs page names this item.	The props of the element, typed MarkdownLeafProps.	Type: MarkdownLeafProps.
press	Documented: An official docs page names this item.	Where the onLinkPress handler lives: the plugin whose hook drew the element, and the handle that its environment keeps the closure under.	Type: object. The runtime stamps the plugin as the tree leaves that hook.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A region that one of the SURFACE MODULES of the plugin, named by path, draws and handles input for on the drawing thread, without $ (ClientModule).	Type: 'Client'. One instance for each plugin. It lives while the node stays in the tree and talks to the plugin through ui.message.
props	Documented: An official docs page names this item.	The props of the element, typed ClientProps.	Type: ClientProps.
client	Documented: An official docs page names this item.	Whose surface module props.module names: the plugin whose hook drew the element. The runtime stamps it as the tree leaves it.	Type: object.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A vector drawing, for the remote surfaces alone. The SVG markup is the data of the element, drawn in an isolated box, off the page.	Type: 'Svg'. A leaf. A surface whose table lacks it refuses the tree. Put a press that others should see on an enclosing Button.
props	Documented: An official docs page names this item.	The props of the element, typed SvgProps.	Type: SvgProps.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A grid of terminal cells, for the terminal surface alone. Each cell is a glyph, a foreground and a background, packed in props.cells.	Type: 'Raster'. A leaf, one node however many cells. $.ui.blit repaints it in place. A surface whose table lacks it refuses the tree.
props	Documented: An official docs page names this item.	The props of the element, typed RasterProps.	Type: RasterProps.
raster	Documented: An official docs page names this item.	Whose Raster: the plugin whose hook drew the element. The runtime stamps it as the tree leaves it. It is the one plugin whose blit reaches it.	Type: object.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	A picture, for the terminal surface alone. props.source is drawn over a box of cells where the terminal can, and props.alt where it cannot.	Type: 'Image'. A leaf. $.ui.blit swaps its picture. A surface without it refuses the tree.
props	Documented: An official docs page names this item.	The props of the element, typed ImageProps.	Type: ImageProps.
image	Documented: An official docs page names this item.	Whose Image: the plugin whose hook drew the element. The runtime stamps it as the tree leaves it. It is the one plugin whose blit reaches it.	Type: object.
children	Documented: An official docs page names this item.	Never set in this form.	Type: undefined. Optional.
type	Documented: An official docs page names this item.	The component that core draws itself, with the props held under ref.	Type: 'engine'.
ref	Documented: An official docs page names this item.	Which drawing: the number that core answered from next(e), under which it holds the props that it received. 0 draws the original props.	Type: number.

RenderInputOf

One ui.render input, for a component narrowed to one surface.

Field	Status	What it is for	Type and limits
surface	Documented: An official docs page names this item.	Where the tree will be drawn, one literal for each member, so if (e.surface === "terminal") narrows e and $.ui.resolve(e).	Type: P. Over the wire it is what the client declared. It is a rendering fact and not a trust signal, so do not key policy on it.
component	Documented: An official docs page names this item.	Which component this instance is, the key a matcher narrows on.	Type: C.
requestId	Documented: An official docs page names this item.	The instance: the tool_use_id for a dialog or tool row, the message id for a message, or the agent id for a spinner.	Type: string. Two drawings of one component are two instances.
viewport	Documented: An official docs page names this item.	The size that the surface draws into, in character cells, and whether its layout docks a pane. Absent where no surface has measured.	Type: RenderViewport. Optional. Part of the envelope, so a rewrite keeps it. A change of width re-draws every hooked site once the resize settles.
props	Documented: An official docs page names this item.	The plain-data props of the component.	Type: RenderPropsOf[C].

RenderResultOf

What a ui.render hook returns and what next(e) resolves to: a RenderElement tree, the same for every component.

Field	Status	What it is for	Type and limits
[C in RenderComponent]	Documented: An official docs page names this item.	For each component, a RenderElement tree.	Type: RenderElement.

RenderViewport

The size that a surface draws into, in character cells of the monospace metric of the surface, and whether its layout docks a pane. On the terminal it is the columns and rows of the conversation. On a remote surface it is the pane size.

Field	Status	What it is for	Type and limits
columns	Documented: An official docs page names this item.	Cells across. A tree wider than this wraps or truncates, as its Text props say.	Type: number.
rows	Documented: An official docs page names this item.	Cells down the whole surface, not the room left for this component.	Type: number. Informational. A change of height alone re-draws nothing and keys no new evaluation, so a hook reads it as of the last width or props change.
isFullscreen	Documented: An official docs page names this item.	Whether this surface docks a pane beside the transcript, so a pane that a plugin opens unasked is a sidebar, not a takeover. Absent means unknown.	Type: boolean. Optional. The terminal always says it: true is fullscreen. A remote surface reports it with its size. A change re-draws.

Related Pages

• UI Types
• Mod API Types