insta-ui

📖 Introduction

insta-ui is a Python-based UI library for quickly building user interfaces.

⚙️ Features

Three modes:

• web mode: generates a stateless web application.
• Web View mode: generates a web view application, which can be packaged as a local app (no need to start a web service).
• Zero mode: generates a pure HTML file that can run directly in a browser without installing any dependencies.

📦 Installation

Zero mode:

pip install instaui -U

uv add instaui

web mode

pip install instaui[web] -U

uv add instaui[web]

Web View mode

pip install instaui[webview] -U

uv add instaui[webview]

🖥️ Quick Start

Install the TDesign UI library:

uv add instaui-tdesign[web]

# main.py
from instaui import ui
from instaui_tdesign import td

td.use(locale="en_US")

@ui.page('/')
def home():
    ui.text("Hello, world!")

ui.server(debug=True).run()

📚 Getting Started

Below is a simple example of summing two numbers. The text color of the result changes dynamically based on whether the result is even or odd.

from instaui import ui
from instaui_tdesign import td

td.use(locale="en_US")

@ui.page('/')
def home():
    num1 = ui.state(0)
    num2 = ui.state(0)

    # When num1 or num2 changes, result will be automatically recalculated
    @ui.computed(inputs=[num1, num2])
    def result(num1: int, num2: int):
        return num1 + num2

    # When result changes, text_color will be automatically updated
    @ui.computed(inputs=[result])
    def text_color(result: int):
        return "red" if result % 2 == 0 else "blue"

    # UI
    td.input_number(num1, theme="column")
    ui.text("+")
    td.input_number(num2, theme="column")
    ui.text("=")
    ui.text(result).style({"color": text_color})

# When deploying a web app, remove debug=True
ui.server(debug=True).run()

Replace ui.server().run() with ui.webview().run() to run in web view mode:

...

# ui.server(debug=True).run()
ui.webview().run()

Methods bound with ui.computed are executed on the server side. If you want to run calculations on the client side, use ui.js_computed.

from instaui import ui
from instaui_tdesign import td

td.use(locale="en_US")

@ui.page('/')
def home():
    num1 = ui.state(0)
    num2 = ui.state(0)

    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")

    # UI
    ...

...

In this case, all interactions are executed in the browser (client side). With zero mode, you can generate a pure HTML file that works without installing any dependencies:

from instaui import ui, zero
from instaui_tdesign import td

td.use(locale="en_US")

@ui.page('/')
def home():
    ...

zero().to_html(home, file='index.html')