Neony

Reactive desktop UI framework for Python, built on LumiView.

中文文档 · API Reference (EN) · API 参考 (中文) · Contributing

Overview

Status: alpha — the API is still settling. Feedback and contributions are welcome.

Neony renders a reactive DOM in a native window. You compose your UI from Python objects — components, layouts, styles — and Neony diff-updates the browser DOM automatically. No HTML, no JavaScript.

It builds on LumiView, which uses the same Rust tao/wry webview stack as Tauri.

• Pure Python API — components, layouts and events, no need for non-python codes
• Fine-grained reactivity — Signal / Computed / Effect primitives with declarative bindings
• Dirty-subtree diffing — only changed elements re-serialize; unchanged subtrees reuse cached snapshots
• Style direct-patch — pure style/attr changes (hover, focus, press) patch straight from the snapshot cache, skipping serialization and diff
• Same stack as Tauri — Rust tao/wry webviews via LumiView
• 3 theme presets — dark / light / deep-blue via CSS custom properties
• (Optional) Frosted glass — translucent surfaces with backdrop blur
• Colour-matched glow — focus rings and hover glows tinted with each element's semantic colour
• Scroll indicator — native scrollbars are hidden; scroll surfaces get a theme-matched floating thumb (faint at rest, strengthens on scroll/hover, draggable, click-to-page) plus a dynamic edge fade that only shows where content actually overflows
• Custom window chrome — frameless, transparent, custom TitleBar
• (Supported platform only) Native window effects — blur / acrylic / mica materials

Installation

pip install neony

Requires Python 3.11+ and the platform WebView stack (WebKitGTK on Linux, WebView2 on Windows, WKWebView on macOS). X11 is not supported — see the Roadmap. The system tray needs libayatana-appindicator on Linux.

Quick Start

from neony.application import Page, launch
from neony.application.elements import Button, Heading, Text, VStack

counter = Button("Click me")


async def on_click(event) -> None:
    counter.label = "Clicked!"


counter.on_click(on_click)

page = Page(gap="16px").add(
    VStack(
        Heading("Hello, Neony", level=1),
        Text("Build desktop UI in pure Python.", role="secondary"),
        counter,
        gap="12px",
    )
)

launch(page, title="My App", width=480, height=360, devtools=True)

Components

Import from neony.application.elements.

All components share a fluent, chainable API — see the API reference for usage.

Window Features

• Frameless custom titlebar — set decorations=False, add a TitleBar, and drag / minimize / maximize / close all work automatically. See docs/api.en.md and the demo_custom_window.py demo.
• Transparent windows & native effects — transparent=True plus apply_blur(), apply_acrylic(), apply_mica(). See demo_transparent_panel.py.
• Programmatic window control — set_title(), set_size(), minimize(), toggle_maximize(), close(), … all on NeonApplication, with window_index=0 for multi-window apps.
• Multi-window — run(*pages) opens one window per page, all sharing one event loop and app.state. launch([...]) accepts a list. See demo_multi_window.py.
• System tray — app.tray = Tray(icon, tooltip, items=[...]) adds a tray icon with a native context menu; close_to_tray=True hides the app instead of quitting on close. Linux needs libayatana-appindicator. See demo_tray.py.

Theming

Three built-in presets — DARK (default), LIGHT, DEEP_BLUE — exposed as CSS custom properties on :root, so a theme switch redraws the whole UI with zero DOM diff. Scrollbars and interaction glows (focus rings, hover halos) reference the same --color-* tokens, so they follow theme switches too. See the API reference for switching and custom themes.

Demos

Run from the repository root:

uv run demo_gallery.py

Roadmap

Planned work lives in ROADMAP.md — performance, events, lifecycle, components, animation, platform integration and verification.

Development

This project uses uv as the environment manager and runner.

uv sync --group dev   # install dependencies (incl. dev tools)
npm ci                # install JS dev dependencies (vitest, jsdom)

uv run demo_gallery.py            # run a demo
uv run pytest -q                  # run the Python test suite
uv run ruff check .               # lint
uv run ruff format --check .      # format check
uv run pyrefly check              # type check
npm test                          # run the JS test suite (vitest)

License

Apache-2.0 © HarcicYang