flet-terminal

Native GPU-accelerated terminal control for Flet apps.

A 1:1 wrapping of the xterm.dart terminal engine, in the same architecture as flet-ads. One uv add flet-terminal covers Windows, Linux, macOS, Android and Web — no Python dependencies beyond flet (CI-verified on Flet 1.0.0 through the latest 1.0.x).

The control is view-only by design: it renders and streams bytes over a DataChannel; your app owns the child process (a local pty, an SSH/WebSocket session, anything). That separation is what makes the same package work in a desktop demo, in CollabShell (remote Colab pty), and in local-proot mobile apps.

Test it without an account

Every release builds the demo app for every platform. Sideload or unpack any of them and every button is live:

Plain flet run launches the prebuilt client without the extension's Dart half — the terminal needs a built app (an artifact above, or flet build <platform>).

Platform Support

The control itself is pure Dart rendering (xterm.dart), so it runs wherever Flet runs. The demo app's local-pty service uses POSIX openpty (Windows demo uses WinPTY transport); mobile hosts own their own process/session layer.

Usage

uv add flet-terminal

The recommended entry point is the MobileTerminal composite — terminal + search bar + virtual extra-keys bar with sticky CTRL/ALT and zoom/settings:

import flet as ft
from flet_terminal import MobileTerminal, BUILTIN_THEMES


@ft.component
def App():
    page = ft.context.page
    mt, _ = ft.use_state(lambda: MobileTerminal(
        show_extra_keys=True,
        show_search=False,
        scrollback=10000,
        font_family="JetBrains Mono",
        theme=BUILTIN_THEMES["JetBrains Dark"],
    ))

    # Your process layer: forward terminal bytes to a pty/SSH/kernel here.
    mt.set_on_bytes(lambda payload: mt.send_bytes(payload))

    return ft.Column(controls=[mt], spacing=0, expand=True)


def main(page: ft.Page):
    page.title = "My Terminal"
    page.theme_mode = ft.ThemeMode.DARK
    page.padding = 0
    page.render(App)


ft.run(main)

MobileTerminal constructs anywhere — inside a component tree, in a plain main(), or from a background task; no renderer context needed.

For just the viewport, use Terminal directly:

import flet as ft
from flet_terminal import Terminal, BUILTIN_THEMES


def main(page: ft.Page):
    term = Terminal(scrollback=10000, theme=BUILTIN_THEMES["Dracula"], expand=True)

    def on_terminal_input(data: bytes):
        term.send_bytes(data)  # echo / forward to your process layer

    term.set_on_bytes(on_terminal_input)
    page.add(term)
    term.write("\x1b[1;32mWelcome to FletTerminal!\x1b[0m\r\n> ")


ft.run(main)

Controls

Terminal Properties

Terminal Methods

Event handlers

Built-in shortcuts (on_shortcut)

MobileTerminal Additional Methods & Properties

ExtraKeysBar Constructor

The default layout: ESC, TAB, CTRL, ALT, ↑ ↓ ← →, - / | ~ ^. Sticky CTRL transforms a→\x01 (case-folded via code−96/code−64); sticky ALT prefixes ESC — the mirror of the Dart-side hardware-key transform.

Configuration

Ctrl/Alt stickiness, themes, zoom, cursor and the search bar are all reachable from the gear menu (show_settings=True) and mirrored in the corresponding Python API above — pick whichever layer your app prefers.

Limitations

• View-only by design. No spawn/pty API: the package renders bytes and reports events; your app owns the process (local pty.openpty, remote WebSocket, kernel client…). The channel is named pty for transport reasons only.
• Built-in themes are plain ANSI dictionaries. Dart accepts extra keys (brightBlack…brightWhite, searchHit*) that fall back to the default theme; the four BUILTIN_THEMES ship exactly twelve keys each.
• get_selection_async never queues (request/response): it returns None while the Dart view is not ready — retry after on_mount.
• Search is linear over the scrollback (xterm has no index); the match counter reflects the Dart-side count.

Example

The standalone demo (all artifacts above) lives at examples/flet_terminal_example — a full MobileTerminal + local-pty app, cross-platform.

Frozen-Control Support

Flet 1.0's declarative renderer stamps _frozen = True on component-rendered controls. Imperative mutations then raise RuntimeError: Frozen controls cannot be updated. flet_terminal handles this internally via thaw(); all MobileTerminal/ExtraKeysBar/TerminalSearchBar mutations already use it — no extra wrapping needed by consumers. If you build your own long-lived controls in a declarative tree, the pattern is:

from flet_terminal.frozen_support import thaw

with thaw(some_control):
    some_control.style = new_style
    some_control.update()

License

This project is licensed under the MIT License. See LICENSE for details.