Textual Autocomplete

4.0.6 verified Mon Apr 27 auth: no python

A library to add autocomplete dropdowns to Textual apps. Current version 4.0.6, requires Python >=3.9. Simplifies building interactive CLI applications with autocomplete widgets.

pip install textual-autocomplete

Common errors

error ModuleNotFoundError: No module named 'textual_autocomplete' ↓

cause Library not installed or virtual environment not activated.

fix

Run 'pip install textual-autocomplete' in your environment.

error ImportError: cannot import name 'DropdownItem' from 'textual_autocomplete' ↓

cause Old import path from version <4.0; DropdownItem was moved to main module.

fix

Use 'from textual_autocomplete import DropdownItem'.

error AttributeError: 'AutoComplete' object has no attribute 'items' ↓

cause Trying to set 'items' as an attribute after initialization; items are managed via reactive property.

fix

Use widget.mount() or reactive: self.query_one(AutoComplete).items = new_items.

Warnings

breaking In version 4.0, the import path for DropdownItem changed. Previously it was 'from textual_autocomplete.items import DropdownItem'; now it's 'from textual_autocomplete import DropdownItem'. ↓

fix Update imports: 'from textual_autocomplete import DropdownItem'.

gotcha AutoComplete must be used inside a Textual App. It will not render standalone or outside of a Textual event loop. ↓

fix Wrap your autocomplete usage within a Textual Application.

gotcha Dropdown items are filtered client-side only; if you need server-side filtering, you must manage the items list programmatically. ↓

fix Use a callback or reactive attribute to update the items list dynamically based on user input.

Imports

AutoComplete

wrong

from textual_autocomplete_autocomplete import AutoComplete

correct

from textual_autocomplete import AutoComplete

Wrong import from older API versions or confusion with internal module structure.

DropdownItem
wrong
```
from textual_autocomplete.items import DropdownItem
```
correct
```
from textual_autocomplete import DropdownItem
```
Old import path from version <4.0; DropdownItem is now directly exported from main module.

Quickstart

A minimal Textual app with an autocomplete widget.

from textual.app import App, ComposeResult
from textual_autocomplete import AutoComplete, DropdownItem

class MyApp(App):
    def compose(self) -> ComposeResult:
        yield AutoComplete(items=[DropdownItem("apple"), DropdownItem("banana")])

app = MyApp()
app.run()