Skip to content

Command

The Textual command palette.

See the guide on the Command Palette for full details.

Hits module-attribute

Hits: TypeAlias = AsyncIterator['DiscoveryHit | 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.

Parameters
Parameter Default Description
prompt
RenderableType
required

The prompt for the option.

command
DiscoveryHit | Hit
required

The details of the command associated with the option.

id
str | None
None

The optional ID for the option.

disabled
bool
False

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: _SystemModalScreen[CallbackType]

The Textual command palette.

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding(
        "ctrl+end, shift+end",
        "command_list('last')",
        show=False,
    ),
    Binding(
        "ctrl+home, shift+home",
        "command_list('first')",
        show=False,
    ),
    Binding("down", "cursor_down", show=False),
    Binding("escape", "escape", "Exit the command palette"),
    Binding(
        "pagedown", "command_list('page_down')", show=False
    ),
    Binding(
        "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

COMPONENT_CLASSES: set[str] = {
    "command-palette--help-text",
    "command-palette--highlight",
}
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.

Closed class

Bases: Message

Posted to App when the command palette is closed.

option_selected instance-attribute

option_selected: bool

True if an option was selected, False if the palette was closed without selecting an option.

Opened class

Bases: Message

Posted to App when the command palette is opened.

OptionHighlighted class

Bases: Message

Posted to App when an option is highlighted in the command palette.

highlighted_event instance-attribute

highlighted_event: OptionList.OptionHighlighted

The option highlighted event from the OptionList within the command palette.

is_open staticmethod

def is_open(app):

Is the command palette current open?

Parameters
Parameter Default Description
app
App
required

The app to test.

Returns
Type Description
bool

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

DiscoveryHit class

Holds the details of a single command search hit.

command instance-attribute

command: IgnoreReturnCallbackType

The function to call when the command is chosen.

display instance-attribute

display: RenderableType

A string or Rich renderable representation of the hit.

help instance-attribute class-attribute

help: str | None = None

Optional help text for the command.

prompt property

prompt: RenderableType

The prompt to use when displaying the discovery hit in the command palette.

text instance-attribute class-attribute

text: str | None = None

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

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

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 instance-attribute class-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.

prompt property

prompt: RenderableType

The prompt to use when displaying the hit in the command palette.

score instance-attribute

score: float

The score of the command hit.

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

text instance-attribute class-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.

Parameters
Parameter Default Description
query
str
required

A query as typed in by the user.

match_style
Style | None
None

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

case_sensitive
bool
False

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.

Parameters
Parameter Default Description
candidate
str
required

The candidate string to match against the query.

Returns
Type Description
Text

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

match method

def match(self, candidate):

Match the candidate against the query.

Parameters
Parameter Default Description
candidate
str
required

Candidate string to match against the query.

Returns
Type Description
float

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.

Parameters
Parameter Default Description
screen
Screen[Any]
required

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.

discover async

def discover(self):

A default collection of hits for the provider.

Yields:

Type Description
Hits

Instances of DiscoveryHit.

Note

This is different from search in that it should yield DiscoveryHits that should be shown by default (before user input).

It is permitted to not implement this method.

matcher method

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

Create a fuzzy matcher for the given user input.

Parameters
Parameter Default Description
user_input
str
required

The text that the user has input.

case_sensitive
bool
False

Should matching be case sensitive?

Returns
Type Description
Matcher

A fuzzy matcher object for matching against candidate hits.

search abstractmethod async

def search(self, query):

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

Parameters
Parameter Default Description
query
str
required

The user input to be matched.

Yields:

Type Description
Hits

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 instance-attribute class-attribute

icon: var[str] = var('🔎')

The icon to display.