UI Engine Overview

Start with the guide

The way to build screens is a page with ui:* elements, opened with quantum start, quantum console or quantum desktop — see One App, Many Screens. The core set of elements listed there is drawn the same in the browser, the console and the desktop window (SPEC UI-7); the other elements on these reference pages work in the browser only and are Experimental. Examples below written as <q:application type="ui"> are standalone builds: layout only (UI-8).

The Quantum UI Engine is a cross-platform UI framework that allows you to build rich user interfaces using declarative XML syntax. Write once, deploy to HTML, Desktop, Mobile, or Terminal.

Key Features

40+ UI Components - Forms, tables, cards, modals, charts, and more
Multi-Target Rendering - Single codebase compiles to multiple platforms
Design Tokens - Consistent styling across all targets
Reactive State - Automatic UI updates when state changes
Built-in Theming - Dark/light modes and custom themes
Animation System - Declarative animations with triggers

Getting Started

Basic UI Application

xml

<q:application id="myapp" type="ui" xmlns:q="https://quantum.lang/ns"
               xmlns:ui="https://quantum.lang/ui">

  <ui:window title="My First App">
    <ui:vbox padding="lg" gap="md">
      <ui:text size="2xl" weight="bold">Welcome to Quantum UI!</ui:text>
      <ui:button variant="primary">Click Me</ui:button>
    </ui:vbox>
  </ui:window>

</q:application>

Build Commands

bash

# Build for HTML (web browser) -> myapp.html
quantum run myapp.q --target html

# Build for Terminal (Textual TUI) -> myapp_console.py
quantum run myapp.q --target textual

# Build for Mobile (React Native, Laboratory) -> myapp.js
quantum run myapp.q --target mobile

# Desktop: --target desktop was removed in 0.16. Write the screens as pages
# in components/ and run them in a window with `quantum desktop`.

Component Categories

Layout Components

Control the structure and arrangement of UI elements.

Component	Description
`ui:window`	Root container for UI applications
`ui:hbox`	Horizontal layout container
`ui:vbox`	Vertical layout container
`ui:grid`	CSS Grid-based layout
`ui:panel`	Bordered container with optional title
`ui:tabs`	Tabbed navigation container
`ui:accordion`	Collapsible sections

Form Components

User input and form controls.

Component	Description
`ui:form`	Form container with validation
`ui:formitem`	Label and input wrapper
`ui:input`	Text input field
`ui:button`	Clickable button
`ui:checkbox`	Checkbox input
`ui:switch`	Toggle switch
`ui:select`	Dropdown select
`ui:radio`	Radio button group

Data Display Components

Display and visualize data.

Component	Description
`ui:table`	Data table with columns
`ui:list`	Ordered/unordered lists
`ui:tree`	Hierarchical tree view
`ui:chart`	Data visualization charts

Feedback Components

User feedback and notifications.

Component	Description
`ui:alert`	Alert messages
`ui:loading`	Loading spinners
`ui:progress`	Progress bars
`ui:badge`	Status badges
`ui:skeleton`	Loading placeholders

Navigation and wayfinding.

Component	Description
`ui:tabs`	Tab navigation
`ui:breadcrumb`	Breadcrumb trail
`ui:pagination`	Page navigation
`ui:menu`	Navigation menu

Overlay Components

Modals, tooltips, and dropdowns.

Component	Description
`ui:modal`	Modal dialogs
`ui:tooltip`	Hover tooltips
`ui:dropdown`	Dropdown menus

Advanced Components

Rich UI components for complex use cases.

Component	Description
`ui:card`	Card containers
`ui:avatar`	User avatars
`ui:chart`	Data charts

Design Tokens

Design tokens ensure consistent styling across all targets. Tokens are normalized values that translate to platform-specific implementations.

Spacing Tokens

Token	HTML Value	Terminal Value
`xs`	4px	1 char
`sm`	8px	1 char
`md`	16px	2 chars
`lg`	24px	3 chars
`xl`	32px	4 chars

xml

<ui:vbox padding="lg" gap="md">
  <!-- Content with large padding and medium gap -->
</ui:vbox>

Size Tokens

Token	Description
`auto`	Automatic sizing
`fill`	Fill available space
`1/2`	50% width
`1/3`	33.3% width
`1/4`	25% width
`2/3`	66.6% width
`3/4`	75% width

xml

<ui:hbox>
  <ui:panel width="1/3">Sidebar</ui:panel>
  <ui:panel width="2/3">Main Content</ui:panel>
</ui:hbox>

Color Tokens

Token	Description
`primary`	Primary brand color
`secondary`	Secondary color
`success`	Success/positive state
`danger`	Error/negative state
`warning`	Warning state
`info`	Informational state
`light`	Light background
`dark`	Dark background

xml

<ui:button variant="primary">Submit</ui:button>
<ui:alert variant="success">Operation completed!</ui:alert>
<ui:badge variant="danger">Error</ui:badge>

Typography Tokens

Token	Description
`xs`	Extra small (12px)
`sm`	Small (14px)
`md`	Medium (16px)
`lg`	Large (20px)
`xl`	Extra large (24px)
`2xl`	2x large (32px)

xml

<ui:text size="2xl" weight="bold">Large Heading</ui:text>
<ui:text size="sm" color="muted">Small helper text</ui:text>

Reactive State Binding

Bind UI components to state variables for automatic updates:

xml

<q:application id="counter" type="ui" xmlns:q="https://quantum.lang/ns"
               xmlns:ui="https://quantum.lang/ui">

  <q:set name="count" value="0" type="number" />

  <q:function name="increment">
    <q:set name="count" value="{count + 1}" />
  </q:function>

  <q:function name="decrement">
    <q:set name="count" value="{count - 1}" />
  </q:function>

  <ui:window title="Counter">
    <ui:vbox padding="lg" gap="md" align="center">
      <ui:text size="2xl">{count}</ui:text>
      <ui:hbox gap="sm">
        <ui:button on-click="decrement">-</ui:button>
        <ui:button on-click="increment">+</ui:button>
      </ui:hbox>
    </ui:vbox>
  </ui:window>

</q:application>

Event Handling

Click Events

xml

<ui:button on-click="handleClick">Click Me</ui:button>

<q:function name="handleClick">
  <q:set name="message" value="Button clicked!" />
</q:function>

Form Events

xml

<ui:form on-submit="handleSubmit">
  <ui:formitem label="Name">
    <ui:input bind="userName" />
  </ui:formitem>
  <ui:button type="submit">Submit</ui:button>
</ui:form>

Change Events

xml

<ui:input bind="searchQuery" on-change="handleSearch" />
<ui:select bind="selectedOption" on-change="handleSelection" />

Targets

HTML Target

Generates standalone HTML with CSS and JavaScript. Suitable for web applications.

bash

quantum run app.q --target html

Desktop Target

--target desktop was removed in 0.16. The same pages the browser serves run in a native window with quantum desktop (see Desktop).

bash

quantum desktop

Mobile Target

Generates React Native code for iOS and Android apps.

bash

quantum run app.q --target mobile   # writes app.js (Laboratory, see UI-8)

Terminal Target

Generates a Textual TUI application for terminal interfaces.

bash

quantum run app.q --target textual
python app_console.py  # Run in terminal

Complete Example

xml

<q:application id="taskmanager" type="ui" xmlns:q="https://quantum.lang/ns"
               xmlns:ui="https://quantum.lang/ui">

  <q:set name="tasks" value='[]' type="array" />
  <q:set name="newTaskName" value="" />
  <q:set name="filter" value="all" />

  <q:function name="addTask">
    <q:if condition="newTaskName != ''">
      <q:set name="tasks" operation="append" value='{
        "id": "{Date.now()}",
        "name": "{newTaskName}",
        "completed": false
      }' />
      <q:set name="newTaskName" value="" />
    </q:if>
  </q:function>

  <q:function name="toggleTask">
    <q:param name="taskId" type="string" />
    <!-- Toggle task completion -->
  </q:function>

  <ui:window title="Task Manager">
    <ui:vbox padding="lg" gap="md">

      <ui:header>
        <ui:text size="2xl" weight="bold">My Tasks</ui:text>
      </ui:header>

      <ui:form on-submit="addTask">
        <ui:hbox gap="sm">
          <ui:input
            bind="newTaskName"
            placeholder="Enter a new task..."
            width="fill"
          />
          <ui:button type="submit" variant="primary">Add</ui:button>
        </ui:hbox>
      </ui:form>

      <ui:tabs>
        <ui:tab label="All" active="{filter == 'all'}" on-click="setFilter('all')">
          <q:loop type="array" var="task" items="{tasks}">
            <ui:hbox gap="sm" padding="sm">
              <ui:checkbox
                checked="{task.completed}"
                on-change="toggleTask(task.id)"
              />
              <ui:text>{task.name}</ui:text>
            </ui:hbox>
          </q:loop>
        </ui:tab>
        <ui:tab label="Active">
          <!-- Active tasks -->
        </ui:tab>
        <ui:tab label="Completed">
          <!-- Completed tasks -->
        </ui:tab>
      </ui:tabs>

      <ui:footer>
        <ui:text color="muted">{tasks.length} tasks total</ui:text>
      </ui:footer>

    </ui:vbox>
  </ui:window>

</q:application>

Next Steps

Layout Components - Structure your UI
Form Components - User input handling
Data Display - Tables, lists, and trees
Theming - Customize appearance
Animations - Add motion

UI Engine Overview ​

Key Features ​

Getting Started ​

Basic UI Application ​

Build Commands ​

Component Categories ​

Layout Components ​

Form Components ​

Data Display Components ​

Feedback Components ​

Navigation Components ​

Overlay Components ​

Advanced Components ​

Design Tokens ​

Spacing Tokens ​

Size Tokens ​

Color Tokens ​

Typography Tokens ​

Reactive State Binding ​

Event Handling ​

Click Events ​

Form Events ​

Change Events ​

Targets ​

HTML Target ​

Desktop Target ​

Mobile Target ​

Terminal Target ​

Complete Example ​

Next Steps ​

UI Engine Overview

Key Features

Getting Started

Basic UI Application

Build Commands

Component Categories

Layout Components

Form Components

Data Display Components

Feedback Components

Navigation Components

Overlay Components

Advanced Components

Design Tokens

Spacing Tokens

Size Tokens

Color Tokens

Typography Tokens

Reactive State Binding

Event Handling

Click Events

Form Events

Change Events

Targets

HTML Target

Desktop Target

Mobile Target

Terminal Target

Complete Example

Next Steps