InteracTUI

Build interactive TUI applications based on the curses library.

InteracTUI provides a base App class that encapsulates a single-column layout made of Views.

Example

A basic TUI might look like :

from interactui import App, View
from interactui.view import Select, TextArea
from interactui.view.select import SelectOption


def quit_function(app: App, _view: View) -> None:
    app.print("Bye !")

    app.exit(0)


App().run(
    [
        TextArea("👋 Hi form InteracTUI", style={"border": "rounded", "margin": 5, "padding": (2, 10)}),
        Select("What do you want to do ?", ["Not much", SelectOption("Quit", callback=quit_function)]),
    ]
)

Views

An app's layout is a collection of View objects. You can define your own views by inheriting from the View class or you can use one of the predefined views :

• Select - select an option from multiple options
• MultiSelect - select one or more options from a checkbox-style list of options
• TextArea - display text
• TextAreaWithButton - display text with a dismissal button
• FloatingView - base for floating views

Key-bindings

Apps and Views can define attached key-bindings with associated callback functions executed on the key press. Key-bindings are defined in the _key_bindings class variable.

class App:  # or View
    _key_bindings: ClassVar[list[KeyBinding]] = [...]

    ...

A key-bindings is made of :

• a Key
• a description
• a callback function (App | View, Key, App) -> None

An App comes with the following base key-bindings:

• <Ctrl-d> - Exit the app
• <Ctrl-k> - show key bindings

Predefined Views come with their key-bindings but you can also define your own. When inheriting form the View class, add your key-bindings in the _key_bindings class variable.

Style

The appearance of Views can be customized with the style parameter, taking a Style dictionary with the following format:

class Style(TypedDict, total=False):
    # all sides | (top & bottom, left & right) | (top, right, bottom, left)
    margin: SidesAmount

    # all sides | (top & bottom, left & right) | (top, right, bottom, left)
    padding: SidesAmount

    # border:
    # - "none": no border
    # - "rounded": rounded corners
    # - "squared": squared corners
    border: Corner

    # foreground font color
    color: Color

    # one or more font modifiers:
    # - "bold"
    # - "italic"
    # - "dim"
    # - "blink"
    # - "reverse"
    font_modifier: Modifier | tuple[Modifier, ...]

    # background font color
    background: Color

    # number lines | "x%" where x is in (0, 1), percentage of total height
    height: int | str

    # number columns | "x%" where x is in (0, 1), percentage of total width
    width: int | str

Installation

pip install interactui or uv add interactui