orion-ui

Python library for building interactive notebook UI in Orion. Author controls in a code cell with import orion_ui as ui; Orion renders them as native notebook outputs.

This package is separate from orion-notebook (the orion CLI). Install orion-ui into the same Python environment as your notebook kernel.

Install

pip install orion-ui

Orion managed runtime

If you start Orion with orion and use its managed Jupyter environment (~/.orion/runtime/venv on macOS/Linux, %USERPROFILE%\.orion\runtime\venv on Windows), orion-ui is installed automatically. You do not need a separate install.

External kernel (conda, venv, your own Jupyter)

Install into that kernel's Python:

python -m pip install orion-ui

Then restart the notebook kernel and re-run your cells.

Quick example

Put a component tree as the last expression in a code cell:

import orion_ui as ui

ui.card(
    ui.stack(
        ui.select("model", ["gpt-4.1", "claude-sonnet"], label="Model", default_value="gpt-4.1"),
        ui.slider("temperature", label="Temperature", min=0, max=2, default_value=0.7, step=0.1),
    ),
    title="Controls",
    class_name="controls-card",
)

Read values in later cells:

model = ui.get("model")
temperature = ui.get("temperature")

Run cells when a control changes

Every user-editable, state-bound control accepts an optional on_change action. Target cells must already have stable Orion cell ids:

ui.date_picker(
    "start_date",
    label="Start date",
    on_change={
        "type": "execute_cells",
        "cellIds": ["stable-orion-cell-id"],
    },
)

Orion writes the new value to Python state before running the target cells. Selections, presets, and keyboard nudges run immediately. Typing waits 500 ms after the latest edit, while slider and date-range dragging wait 250 ms. Use debounce_ms=0 for immediate execution or another non-negative millisecond value to override the default. Date ranges run only after both endpoints are selected, and ui.date_time_picker() applies one action to its date, start time, and end time values.

The supported controls are ui.input, ui.textarea, ui.select, ui.slider, ui.checkbox, ui.switch, ui.radio_group, ui.toggle, ui.toggle_group, ui.calendar, ui.date_picker, ui.date_range_slider, and ui.date_time_picker. Prefer an explicit ui.button(..., action=...) when running cells is expensive or destructive.

DataFrame tables

Use ui.table() for interactive pandas DataFrame browsing without sending the entire DataFrame to the frontend:

import orion_ui as ui

ui.table(
    df,
    source="df",
    page_size=50,
    default_filters=[
        {"column": "status", "operation": "equals", "value": "active"},
    ],
    default_sort={"column": "score", "direction": "desc"},
    column_descriptions={
        "score": "Priority score from 1 to 10.",
        "status": "Current account status.",
    },
)

Table filtering, sorting, grouping, stats, and export requests run in the Python kernel. Saved table views are stored on the notebook output metadata as structured operations plus a readable pandas expression. Column descriptions, when provided, appear as info-icon tooltips in table headers.

Use default_filters and default_sort to set the table's initial operations. default_filters accepts the same column, operation, and value shape as the filter menu; default_sort accepts one column and direction ("asc" or "desc"). Resetting the Default view restores these defaults.

Filter operations and controls follow each pandas column's semantic dtype. Text columns provide text matching, ordered numeric and temporal columns provide comparisons and inclusive between, booleans use a true/false selector, and bounded categoricals support in and notIn. Range filters use {"lower": "...", "upper": "..."} as their value, while categorical set filters use a list of values. Date and datetime values use ISO syntax:

default_filters=[
    {
        "column": "created_at",
        "operation": "between",
        "value": {
            "lower": "2026-01-01T00:00:00",
            "upper": "2026-01-31T23:59:59",
        },
    },
]

Versioned outputs

Wrap a rich notebook value with ui.version() to keep earlier successful renders inside the saved notebook output:

t = 5
filtered = df[df > t]

ui.version(filtered.plot())

After the cell runs more than once, hover the output and use the version picker in its upper-right corner. Orion retains the latest 10 versions by default:

ui.version(filtered.plot(), max_versions=5)

Unkeyed wrappers are matched by their order among the versioned outputs in the cell. Add a unique key when a cell contains several versioned outputs that may be reordered:

ui.version(revenue_plot, key="revenue")
ui.version(retention_plot, key="retention")

Failed reruns keep the last successful version history alongside the error. Clearing the output clears its history. Self-contained rich MIME outputs remain available after saving and reopening the notebook; live widgets and kernel-backed controls can still require an active kernel.

class_name adds semantic CSS hooks for Orion UI in Notebook View and App View. Do not write CSS into notebook metadata; if a notebook needs custom styling, include it in the relevant cell source/output and scope selectors to rendered markdown/output areas. Orion also exposes JupyterLab-compatible rendered-content selectors such as .jp-MarkdownOutput, .jp-RenderedHTMLCommon, and .jp-OutputArea-output for cell-authored styles. Do not rely on arbitrary Tailwind classes generated at runtime.

Requirements

• Python 3.8+
• Orion (or another frontend that renders application/vnd.orion.ui+json) for interactive display

Other Jupyter frontends may show a static fallback instead of live controls.

Version coupling

Pin orion-ui to the same version as your Orion app when using managed runtimes (for example orion-ui==0.6.0). The Python output format and Orion's renderer are released together.

Links

• Orion website
• User docs
• Fix: orion_ui import error
• orion-notebook on PyPI (CLI launcher)

License

Apache-2.0