Skip to content


The Textual command palette.

See the guide on the Command Palette for full details.

Hits module-attribute

Hits: TypeAlias = AsyncIterator[Hit]

Return type for the command provider's search method.

Command class

def __init__(self, prompt, command, id=None, disabled=False):

Bases: Option

Class that holds a command in the CommandList.

Name Type Description Default
prompt RenderableType

The prompt for the option.

command Hit

The details of the command associated with the option.

id str | None

The optional ID for the option.

disabled bool

The initial enabled/disabled state. Enabled by default.


command instance-attribute

command = command

The details of the command associated with the option.

CommandInput class

Bases: Input

The command palette input control.

CommandList class

Bases: OptionList

The command palette command list.

CommandPalette class

def __init__(self):

Bases: ModalScreen[CallbackType]

The Textual command palette.

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
        "ctrl+end, shift+end",
        "ctrl+home, shift+home",
    Binding("down", "cursor_down", show=False),
    Binding("escape", "escape", "Exit the command palette"),
        "pagedown", "command_list('page_down')", show=False
        "pageup", "command_list('page_up')", show=False
    Binding("up", "command_list('cursor_up')", show=False),
Key(s) Description
ctrl+end, shift+end Jump to the last available commands.
ctrl+home, shift+home Jump to the first available commands.
down Navigate down through the available commands.
escape Exit the command palette.
pagedown Navigate down a page through the available commands.
pageup Navigate up a page through the available commands.
up Navigate up through the available commands.

COMPONENT_CLASSES class-attribute

Class Description
command-palette--help-text Targets the help text of a matched command.
command-palette--highlight Targets the highlights of a matched command.

run_on_select class-attribute

run_on_select: bool = True

A flag to say if a command should be run when selected by the user.

If True then when a user hits Enter on a command match in the result list, or if they click on one with the mouse, the command will be selected and run. If set to False the input will be filled with the command and then Enter should be pressed on the keyboard or the 'go' button should be pressed.

is_open staticmethod

def is_open(app):

Is the command palette current open?

Name Type Description Default
app App

The app to test.

Type Description

True if the command palette is currently open, False if not.

on_mount method

def on_mount(self, _):

Capture the calling screen.

on_unmount async

def on_unmount(self):

Shutdown providers when command palette is closed.

Hit class

Holds the details of a single command search hit.

command instance-attribute

command: IgnoreReturnCallbackType

The function to call when the command is chosen.

help class-attribute instance-attribute

help: str | None = None

Optional help text for the command.

match_display instance-attribute

match_display: RenderableType

A string or Rich renderable representation of the hit.

score instance-attribute

score: float

The score of the command hit.

The value should be between 0 (no match) and 1 (complete match).

text class-attribute instance-attribute

text: str | None = None

The command text associated with the hit, as plain text.

If match_display is not simple text, this attribute should be provided by the Provider object.

Matcher class

def __init__(
    self, query, *, match_style=None, case_sensitive=False

A fuzzy matcher.

Name Type Description Default
query str

A query as typed in by the user.

match_style Style | None

The style to use to highlight matched portions of a string.

case_sensitive bool

Should matching be case sensitive?


case_sensitive property

case_sensitive: bool

Is this matcher case sensitive?

match_style property

match_style: Style

The style that will be used to highlight hits in the matched text.

query property

query: str

The query string to look for.

query_pattern property

query_pattern: str

The regular expression pattern built from the query.

highlight method

def highlight(self, candidate):

Highlight the candidate with the fuzzy match.

Name Type Description Default
candidate str

The candidate string to match against the query.

Type Description

A [rich.text.Text][Text] object with highlighted matches.

match method

def match(self, candidate):

Match the candidate against the query.

Name Type Description Default
candidate str

Candidate string to match against the query.

Type Description

Strength of the match from 0 to 1.

Provider class

def __init__(self, screen, match_style=None):

Bases: ABC

Base class for command palette command providers.

To create new command provider, inherit from this class and implement search.

Name Type Description Default
screen Screen[Any]

A reference to the active screen.


app property

app: App[object]

A reference to the application.

focused property

focused: Widget | None

The currently-focused widget in the currently-active screen in the application.

If no widget has focus this will be None.

match_style property

match_style: Style | None

The preferred style to use when highlighting matching portions of the match_display.

screen property

screen: Screen[object]

The currently-active screen in the application.

matcher method

def matcher(self, user_input, case_sensitive=False):

Create a fuzzy matcher for the given user input.

Name Type Description Default
user_input str

The text that the user has input.

case_sensitive bool

Should matching be case sensitive?

Type Description

A fuzzy matcher object for matching against candidate hits.

search async abstractmethod

def search(self, query):

A request to search for commands relevant to the given query.

Name Type Description Default
query str

The user input to be matched.



Type Description

Instances of Hit.

shutdown async

def shutdown(self):

Called when the Provider is shutdown.

Use this method to perform an cleanup, if required.

startup async

def startup(self):

Called after the Provider is initialized, but before any calls to search.

SearchIcon class

Bases: Static

Widget for displaying a search icon before the command input.

icon class-attribute instance-attribute

icon: var[str] = var(

The icon to display.