Neony

Reactive desktop UI framework for Python, built on LumiView.

📖 Docs (latest release): https://harcic.me/neony · 中文

These hosted docs point to the latest tag. 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 updates the browser DOM incrementally. 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
• Same stack as Tauri — Rust tao/wry webviews via LumiView
• 8 theme presets — Nightglow / Planet Plaza / Ember Zone / Cyberangel families, each with light and dark material, 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 index for usage.

Window Features

• Frameless custom titlebar — set decorations=False, add a TitleBar, and drag / minimize / maximize / close all work automatically. See docs/api/layout-chrome.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. The managed Video / Audio components hydrate neony:// sources 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. Raw <audio> / <video> DOM elements are not hydrated. 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 — opened asynchronously so the app keeps running while they're up (None on cancel, [] for a cancelled multi-select).

Theming

Eight built-in presets across four visual families — Nightglow, Planet Plaza, Ember Zone, and Cyberangel, each with paired light and dark material — exposed as CSS custom properties on :root; the historical names DARK (default), LIGHT, and DEEP_BLUE remain as aliases. Switching themes replaces the :root variable block, and 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. Motion tokens work the same way: Motion.DEFAULT injects --motion-* variables, with transition() / popup_animation() / submenu_animation() covering common interactions.

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.

Running the demos from source

The demos in the repository root need the development environment described in CONTRIBUTING.md, then:

uv run gallery

Development, testing and documentation conventions live in the contributing guide.

License

Apache-2.0 © HarcicYang