Textual Autocomplete

Textual Autocomplete drops a dropdown suggestion list onto any Input widget in a Textual app with a few lines of code — pass an AutoComplete widget the target Input and a list (or callback) of candidate strings, and it handles showing/filtering the dropdown as the user types, keyboard navigation, and selection.

Beyond a static candidate list, it supports dynamic candidate generation via a callback (useful for async or context-dependent suggestions), fuzzy matching for forgiving substring/typo-tolerant search, and a ready-made PathAutoComplete for filesystem path completion — a common need in CLI-adjacent TUI tools. It targets Textual 2.0+ and is used by terminal applications wanting IDE-style completion without building the dropdown/filtering logic themselves.

What You Get

• An AutoComplete widget that attaches to an existing Input and renders a dropdown of matching candidates as the user types
• Static candidate lists or a callback-based candidate source for dynamic/async suggestions
• Built-in fuzzy search (fuzzy_search.py) for typo-tolerant, substring-based matching instead of exact-prefix-only filtering
• A ready-made PathAutoComplete widget for filesystem path completion, a common need in file-picker-style TUI inputs
• Full keyboard navigation (arrow keys, enter/tab to select, escape to dismiss) with no extra wiring required

Common Use Cases

• Adding command or argument autocomplete to a Textual-based TUI application, similar to a shell’s tab-completion
• File and directory path completion in TUI file pickers or CLI-style input prompts via PathAutoComplete
• Search-as-you-type interfaces where users filter a known list of options (tags, usernames, config keys) from a text input
• Building REPL-like or IDE-like terminal tools that need suggestion dropdowns without reimplementing fuzzy filtering and dropdown positioning

Under The Hood

Architecture — The library is a small, focused Textual widget package: _autocomplete.py defines the core AutoComplete widget that composes alongside a target Input, listening for its value-changed events, invoking the candidate source (list or callback), running the results through fuzzy_search.py’s matcher, and rendering/positioning a dropdown overlay; _path_autocomplete.py builds PathAutoComplete on top of the same core by supplying a filesystem-aware candidate callback. Tech Stack — Pure Python (>=3.9) with textual>=2.0.0 as its only hard runtime dependency (plus typing-extensions), built with Hatchling and managed via uv; the package ships a py.typed marker, and dev tooling includes mypy, pytest with pytest-textual-snapshot for widget-rendering regression tests, and pytest-xdist for parallel test runs. Code Quality — A compact codebase (under 1,000 lines across the package) with 5 test files including Textual’s own snapshot-testing harness, which catches visual/rendering regressions in the dropdown that plain assertion tests would miss; the package is fully typed (py.typed present) and has seen no commits since early 2026, consistent with a small, feature-complete utility rather than one under active expansion. API Design — Getting started is a two-line addition next to an existing Input() — construct AutoComplete(text_input, candidates=[...]) and yield it alongside the input — which keeps the API approachable for Textual developers already familiar with the framework’s compose-based widget model, while the callback-based candidate source and PathAutoComplete subclass cover more advanced dynamic/path-completion needs without complicating the basic case.