# UX Nodes

Build interactive user-facing elements from graphs: choice menus, notices and text inputs, emitted to the interface and styled with **Style Element**.

<!-- glossary:generated - everything below this line is generated by `python -m talemate.game.engine.nodes.tools glossary --write` - do not edit -->


_5 nodes._

| Node | Registry path |
| --- | --- |
| [Build Choice Element](#build-choice-element) | `ux/BuildChoiceElement` |
| [Build Notice Element](#build-notice-element) | `ux/BuildNoticeElement` |
| [Build Text Input Element](#build-text-input-element) | `ux/BuildTextInputElement` |
| [Emit UX Element](#emit-ux-element) | `ux/EmitElement` |
| [Style UX Element](#style-ux-element) | `ux/StyleElement` |

## Build Choice Element

`ux/BuildChoiceElement`

Builds a choice UX element payload.

A random id is generated when none is given. Raises an error if choices is
empty. Emit the resulting element with `ux/EmitElement`.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `id` | `str` | (optional) str (optional; auto-generated when not set) |
| `closable` | `bool` | bool (optional) |
| `timeout_seconds` | `int` | (optional) int (optional; 0 = no timeout) |
| `title` | `str` | str (optional) |
| `body` | `str` | str (optional) |
| `choices` | `list` | list (required) |
| `multi_select` | `bool` | bool (optional) |
| `default` | `any` | str\|list[str] (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `id` | `str` | the element id (resolved) |
| `closable` | `bool` | bool (resolved) |
| `timeout_seconds` | `int` | int (resolved) |
| `title` | `str` | str (resolved) |
| `body` | `str` | str (resolved) |
| `choices` | `list` | list (passed through) |
| `multi_select` | `bool` | bool (resolved) |
| `default` | `any` | the resolved default selection |
| `ux_id` | `str` | str |
| `ux_element` | `ux_element` | dict |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `closable` | `bool` | `True` | Whether the user can dismiss the element (dismissal cancels waiting) |
| `timeout_seconds` | `int` | `0` | Optional timeout for the interaction (0 = no timeout). Min: 0. |
| `element_title` | `str` | `""` | Title for the element |
| `element_body` | `text` | `""` | Body/description for the element |
| `multi_select` | `bool` | `False` | Allow selecting multiple choices |
| `default` | `any` | `None` | Default selection (string or list of strings) |

## Build Notice Element

`ux/BuildNoticeElement`

Builds a notice (display-only) UX element payload.

Fire-and-forget: EmitElement emits and returns immediately. The frontend
renders the notice until the user dismisses it (when closable) or the
client-side timeout expires.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `id` | `str` | (optional) str (optional; auto-generated when not set) |
| `closable` | `bool` | bool (optional) |
| `timeout_seconds` | `int` | int (optional) |
| `title` | `str` | str (optional) |
| `body` | `str` | str (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `id` | `str` | the element id (resolved) |
| `closable` | `bool` | bool (resolved) |
| `timeout_seconds` | `int` | int (resolved) |
| `title` | `str` | str (resolved) |
| `body` | `str` | str (resolved) |
| `ux_id` | `str` | str |
| `ux_element` | `ux_element` | dict |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `closable` | `bool` | `True` | Whether the user can dismiss the element (dismissal cancels waiting) |
| `timeout_seconds` | `int` | `0` | Optional timeout for the interaction (0 = no timeout). Min: 0. |
| `element_title` | `str` | `""` | Title for the element |
| `element_body` | `text` | `""` | Body/description for the element |

## Build Text Input Element

`ux/BuildTextInputElement`

Builds a text input UX element payload.

A random id is generated when none is given. Emit the resulting element
with `ux/EmitElement`.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `id` | `str` | (optional) str (optional; auto-generated when not set) |
| `closable` | `bool` | bool (optional) |
| `timeout_seconds` | `int` | (optional) int (optional; 0 = no timeout) |
| `title` | `str` | str (optional) |
| `body` | `str` | str (optional) |
| `multiline` | `bool` | bool (optional) |
| `rows` | `int` | int (optional) |
| `placeholder` | `str` | str (optional) |
| `default` | `str` | str (optional) |
| `trim` | `bool` | bool (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `id` | `str` | the element id (resolved) |
| `closable` | `bool` | bool (resolved) |
| `timeout_seconds` | `int` | int (resolved) |
| `title` | `str` | str (resolved) |
| `body` | `str` | str (resolved) |
| `multiline` | `bool` | bool (resolved) |
| `rows` | `int` | int (resolved) |
| `placeholder` | `str` | str (resolved) |
| `default` | `str` | str (resolved) |
| `trim` | `bool` | bool (resolved) |
| `ux_id` | `str` | str |
| `ux_element` | `ux_element` | dict |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `closable` | `bool` | `True` | Whether the user can dismiss the element (dismissal cancels waiting) |
| `timeout_seconds` | `int` | `0` | Optional timeout for the interaction (0 = no timeout). Min: 0. |
| `element_title` | `str` | `""` | Title for the element |
| `element_body` | `text` | `""` | Body/description for the element |
| `multiline` | `bool` | `False` | Render as textarea (true) or single-line input (false) |
| `rows` | `int` | `0` | Textarea rows (only used when multiline). Min: 0. |
| `placeholder` | `str` | `""` | Input placeholder text |
| `default` | `str` | `""` | Default input value |
| `trim` | `bool` | `True` | Whether to trim input before submission |

## Emit UX Element

`ux/EmitElement`

Emits a UX element to the frontend (websocket passthrough).

Choice and text input elements are awaitable by design: emitting one will
wait for the user to submit/cancel (with optional element-defined timeout),
then close the UX element and return the captured interaction values.
A timeout is reported as both `timed_out` and `cancelled`. Notice elements
are fire-and-forget and return immediately.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `ux_element` | `ux_element` | dict |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `ux_id` | `str` | str |
| `ux_element` | `ux_element` | dict |
| `value` | `any` | any |
| `values` | `any` | dict |
| `cancelled` | `bool` | bool |
| `timed_out` | `bool` | bool |

## Style UX Element

`ux/StyleElement`

Pass-through node for styling UX elements.

Intended usage: connect between `ux/Build*Element` nodes and `ux/EmitElement`.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `ux_element` | `ux_element` | dict |
| `tint` | `str` | str (optional) - Vuetify color name |
| `icon` | `str` | str (optional) - mdi-* icon name |
| `apply_scene_colors` | `bool` | bool (optional) - render body through the scene-message parser for per-category colors |
| `compact` | `bool` | bool (optional) - render the element in a condensed layout |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | any |
| `ux_id` | `str` | str |
| `ux_element` | `ux_element` | dict |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `tint` | `str` | `"muted"` | Color tint (Vuetify color name). Choices are generated at runtime. |
| `icon` | `str` | `""` | Material Design Icon name (e.g., 'mdi-help-circle-outline', 'mdi-information'). Leave blank for no icon. |
| `apply_scene_colors` | `bool` | `False` | When true, the body text is rendered through the scene-message parser and gets its per-category colors (quotes/emphasis/parentheses/brackets). When false, body renders with markdown formatting but inherits the element's color. |
| `compact` | `bool` | `False` | When true, the frontend renders the element in a condensed layout: smaller icon and text, and the title leads inline into the body rather than sitting on its own row. |