Terminal

A GPU-accelerated native terminal control for Flet apps, powered by xterm.dart.

A native, GPU-accelerated terminal control for Flet, built on top of xterm.dart.

flet-terminal provides high-performance VT100/ANSI terminal emulation across Windows, Linux, macOS, Android, and Web, utilizing low-latency binary DataChannel streaming to render thousands of lines per second without UI freezing.

Fully compatible with Flet 1.0's declarative component model (@ft.component, @ft.observable, use_state, use_effect) — including frozen-control safety via the built-in thaw() context manager.

Features

• High-Throughput Binary Streaming: Routes terminal data over Flet DataChannel directly to the xterm.dart canvas, bypassing string/MsgPack serialization overhead.
• Cross-Platform Compatibility: Full feature parity across Desktop (pty / winpty), Mobile (Android), and Web (WASM / Pyodide).
• Declarative-First Design: Built for Flet 1.0's React-like component model. All internal mutations use thaw() to safely update frozen controls inside declarative trees.
• Leak-Free Host Shortcuts: Built-in combos (Ctrl/Cmd+Shift+T/W/1-9/F/L/C/V, zoom, F1) are intercepted on the Dart side before the PTY — they fire an on_shortcut event and never leak bytes into your shell.
• Responsive Mobile Wrapper & Zoom Controls: MobileTerminal includes zoom_in(), zoom_out(), reset_zoom(), and a customizable virtual accessory keyboard (ESC, TAB, CTRL, ALT, arrows) with sticky modifier toggles and collapsible state.
• Reactive CTRL/ALT Modifiers: Sticky modifier buttons are @ft.component instances subscribed to an @ft.observable ModifierState — they repaint instantly on toggle, reset, or external state change.
• Real Cursor Blink: A Dart-side Timer.periodic toggles cursorVisibleMode + notifyListeners() for true blink (upstream xterm 4.0.0 has no built-in blink).
• 4 Built-in Themes: Dracula, JetBrains Dark, Matrix Green, and Colab Light (Material light palette with orange cursor). Settings popup displays accurate checkmarks that update live.
• Interactive Search & Selection: Built-in search bar with match counter, scrollback control, and clipboard integration (select_all, copy_selection, paste, clear_selection).
• Frozen-Control Safety: The thaw() context manager (exported from flet_terminal.frozen_support) temporarily lifts Flet's _frozen flag so imperative mutations work inside declarative trees — the same pattern Flet uses internally in _before_update_safe.

Installation

Install via pip:

pip install flet-terminal

Or using uv:

uv add flet-terminal

Quickstart

1. Declarative App (Recommended — Flet 1.0)

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,
        show_settings=True,
        scrollback=10000,
        font_family="JetBrains Mono",
        font_size=13.0,
        cursor_blink=True,
        theme=BUILTIN_THEMES["JetBrains Dark"],
        expand=True,
    ))

    def on_bytes(payload: bytes):
        # Echo back or forward to a PTY / remote shell
        mt.send_bytes(payload)

    ft.use_effect(lambda: mt.set_on_bytes(on_bytes), [])

    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)

2. Basic Terminal (Terminal)

import flet as ft
from flet_terminal import Terminal, BUILTIN_THEMES


def main(page: ft.Page):
    page.theme_mode = ft.ThemeMode.DARK

    term = Terminal(
        scrollback=10000,
        font_family="JetBrains Mono",
        font_size=13.0,
        cursor_blink=True,
        theme=BUILTIN_THEMES["Dracula"],
        expand=True,
    )

    def on_terminal_input(data: bytes):
        term.send_bytes(data)

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


ft.run(main)

3. Imperative Construction Inside Async Tasks

If you build MobileTerminal outside a component render (e.g. inside page.run_task), wrap construction in a throwaway renderer so the internal @ft.component buttons can instantiate:

from flet.components.component import Renderer

with Renderer().with_context():
    mt = MobileTerminal(theme=BUILTIN_THEMES["JetBrains Dark"], expand=True)

Reactivity is unaffected — Component.update() creates its own renderer on every re-render.

API Reference

Terminal Properties

Terminal Methods

Terminal Events

Built-in shortcuts (on_shortcut)

MobileTerminal Additional Methods & Properties

ExtraKeysBar Constructor

Built-in Themes

from flet_terminal import BUILTIN_THEMES, get_theme

# Available: "Dracula", "JetBrains Dark", "Matrix Green", "Colab Light"
my_theme = get_theme("Dracula")

Desktop Demo App

Try the standalone Flet Terminal demo application directly on your OS:

Frozen-Control Support

Flet 1.0's declarative renderer stamps _frozen = True on all component-rendered controls. Imperative mutations (.update(), property assignment) raise RuntimeError: Frozen controls cannot be updated.

flet_terminal handles this internally via thaw():

from flet_terminal.frozen_support import thaw

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

All MobileTerminal setters (set_theme, zoom_in, toggle_search, etc.) and ExtraKeysBar mutations already use thaw() internally — no extra wrapping needed by consumers.

License

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