Neony

Reactive desktop UI framework for Python, built on LumiView.

📖 Docs (latest release): https://harcic.is-a.dev/neony · 中文

These hosted docs track the latest tag (v0.2.0). For the latest commit (in-repo docs/), see docs/ — docs/README.en.md, getting-started, api/ chapters.

中文文档 · Contributing

Overview

Status: pre-beta — 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. Application code does not need to write HTML or JavaScript.

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

• Pure Python API — components, layouts and events; no HTML or JavaScript in application code
• 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). Linux development and verification primarily target Wayland; X11 is not a complete support target at this stage. See the installation and platform guide for system packages and troubleshooting. 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
from neony.dom import Signal

clicks = Signal(0)
counter = Button("Click me")
counter.bind_text(clicks, fmt=lambda count: f"Clicked {count} times!" if count else "Click me")
counter.on_click(lambda _event: clicks.update(lambda count: count + 1))

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 automatically applies the platform material (Wayland blur on Linux where the compositor supports it, Acrylic on Windows, Blur on macOS). apply_blur(), apply_acrylic(), and apply_mica() are manual overrides and are platform-limited (apply_blur is macOS/Windows; acrylic / mica are Windows 11). 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.
• Clipboard — app.clipboard_write(text) / app.clipboard_read().
• Local resource URLs — file_url() / data_url() for Windows paths, spaces, and non-ASCII filenames.
• Custom protocols — serve content to the page via neony://<key>/… URLs: declare handlers with @protocol("key") (plain functions or methods) and pass them to launch(page, protocols=[...]). The built-in local_files handler serves local files over neony://local/… with Range support where file:// is blocked by the webview; local_url(path) / protocol_url(key, value) build the URLs. <audio> / <video> sources on a custom scheme are hydrated automatically — the webview's media pipeline can't read custom schemes, so the runtime fetches the bytes and swaps in a Blob URL — and local media plays (and seeks) with no extra work. See demo_protocols.py.
• Internationalization — typed catalogs plus tr / set_language(); bound labels update live on a language switch.
• 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.
• Native file dialogs — app.open_file(), app.open_files(), app.save_file(), app.select_folder() shell out to the platform's own picker — zenity on Linux, osascript on macOS, PowerShell on Windows, tkinter fallback — shown in an executor thread so the app keeps running while they're up (None on cancel, [] for a cancelled multi-select).

Theming

Three built-in presets — DARK (default), LIGHT, DEEP_BLUE — exposed as CSS custom properties on :root. Switching themes replaces that variable block only — no DOM diff; the browser recolors every var(--color-*). Scrollbars and interaction glows (focus rings, hover halos) reference the same tokens, so they follow theme switches too. See the API reference for switching and custom themes.

Demos

Run from the repository root:

uv run gallery

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)

uv run gallery                       # run the component gallery
uv run python scripts/check_all.py   # run the full check suite (ruff / pyrefly / pytest / vitest)

scripts/check_all.py also runs the JavaScript tests (vitest + jsdom). It runs npm ci automatically when node_modules/ is missing.

License

Apache-2.0 © HarcicYang