TextArea¶

A widget for editing text which may span multiple lines. Supports text selection, soft wrapping, optional syntax highlighting with tree-sitter and a variety of keybindings.

• Focusable
• Container

Guide¶

Code editing vs plain text editing¶

By default, the TextArea widget is a standard multi-line input box with soft-wrapping enabled.

If you're interested in editing code, you may wish to use the TextArea.code_editor convenience constructor. This is a method which, by default, returns a new TextArea with soft-wrapping disabled, line numbers enabled, and the tab key behavior configured to insert \t.

Syntax highlighting dependencies¶

To enable syntax highlighting, you'll need to install the syntax extra dependencies:

pip install "textual[syntax]"

poetry add "textual[syntax]"

This will install tree-sitter and tree-sitter-languages. These packages are distributed as binary wheels, so it may limit your applications ability to run in environments where these wheels are not available. After installing, you can set the language reactive attribute on the TextArea to enable highlighting.

Loading text¶

In this example we load some initial text into the TextArea, and set the language to "python" to enable syntax highlighting.

from textual.app import App, ComposeResult
from textual.widgets import TextArea

TEXT = """\
def hello(name):
    print("hello" + name)

def goodbye(name):
    print("goodbye" + name)
"""


class TextAreaExample(App):
    def compose(self) -> ComposeResult:
        yield TextArea.code_editor(TEXT, language="python")


app = TextAreaExample()
if __name__ == "__main__":
    app.run()

To update the content programmatically, set the text property to a string value.

To update the parser used for syntax highlighting, set the language reactive attribute:

# Set the language to Markdown
text_area.language = "markdown"

Reading content from TextArea¶

There are a number of ways to retrieve content from the TextArea:

• The TextArea.text property returns all content in the text area as a string.
• The TextArea.selected_text property returns the text corresponding to the current selection.
• The TextArea.get_text_range method returns the text between two locations.

In all cases, when multiple lines of text are retrieved, the document line separator will be used.

Editing content inside TextArea¶

The content of the TextArea can be updated using the replace method. This method is the programmatic equivalent of selecting some text and then pasting.

Some other convenient methods are available, such as insert, delete, and clear.

Working with the cursor¶

Moving the cursor¶

The cursor location is available via the cursor_location property, which represents the location of the cursor as a tuple (row_index, column_index). These indices are zero-based and represent the position of the cursor in the content. Writing a new value to cursor_location will immediately update the location of the cursor.

>>> text_area = TextArea()
>>> text_area.cursor_location
(0, 0)
>>> text_area.cursor_location = (0, 4)
>>> text_area.cursor_location
(0, 4)

cursor_location is a simple way to move the cursor programmatically, but it doesn't let us select text.

Selecting text¶

To select text, we can use the selection reactive attribute. Let's select the first two lines of text in a document by adding text_area.selection = Selection(start=(0, 0), end=(2, 0)) to our code:

from textual.app import App, ComposeResult
from textual.widgets import TextArea
from textual.widgets.text_area import Selection

TEXT = """\
def hello(name):
    print("hello" + name)

def goodbye(name):
    print("goodbye" + name)
"""


class TextAreaSelection(App):
    def compose(self) -> ComposeResult:
        text_area = TextArea.code_editor(TEXT, language="python")
        text_area.selection = Selection(start=(0, 0), end=(2, 0))  # (1)!
        yield text_area


app = TextAreaSelection()
if __name__ == "__main__":
    app.run()

Note that selections can happen in both directions, so Selection((2, 0), (0, 0)) is also valid.

More cursor utilities¶

There are a number of additional utility methods available for interacting with the cursor.

Location information¶

Many properties exist on TextArea which give information about the current cursor location. These properties begin with cursor_at_, and return booleans. For example, cursor_at_start_of_line tells us if the cursor is at a start of line.

We can also check the location the cursor would arrive at if we were to move it. For example, get_cursor_right_location returns the location the cursor would move to if it were to move right. A number of similar methods exist, with names like get_cursor_*_location.

Cursor movement methods¶

The move_cursor method allows you to move the cursor to a new location while selecting text, or move the cursor and scroll to keep it centered.

# Move the cursor from its current location to row index 4,
# column index 8, while selecting all the text between.
text_area.move_cursor((4, 8), select=True)

The move_cursor_relative method offers a very similar interface, but moves the cursor relative to its current location.

Common selections¶

There are some methods available which make common selections easier:

• select_line selects a line by index. Bound to F6 by default.
• select_all selects all text. Bound to F7 by default.

Themes¶

TextArea ships with some builtin themes, and you can easily add your own.

Themes give you control over the look and feel, including syntax highlighting, the cursor, selection, gutter, and more.

Default theme¶

The default TextArea theme is called css, which takes its values entirely from CSS. This means that the default appearance of the widget fits nicely into a standard Textual application, and looks right on both dark and light mode.

When using the css theme, you can make use of component classes to style elements of the TextArea. For example, the CSS code TextArea .text-area--cursor { background: green; } will make the cursor green.

More complex applications such as code editors may want to use pre-defined themes such as monokai. This involves using a TextAreaTheme object, which we cover in detail below. This allows full customization of the TextArea, including syntax highlighting, at the code level.

Using builtin themes¶

The initial theme of the TextArea is determined by the theme parameter.

# Create a TextArea with the 'dracula' theme.
yield TextArea.code_editor("print(123)", language="python", theme="dracula")

You can check which themes are available using the available_themes property.

>>> text_area = TextArea()
>>> print(text_area.available_themes)
{'css', 'dracula', 'github_light', 'monokai', 'vscode_dark'}

After creating a TextArea, you can change the theme by setting the theme attribute to one of the available themes.

text_area.theme = "vscode_dark"

On setting this attribute the TextArea will immediately refresh to display the updated theme.

Custom themes¶

Using custom (non-builtin) themes is a two-step process:

1. Create an instance of TextAreaTheme.
2. Register it using TextArea.register_theme.

1. Creating a theme¶

Let's create a simple theme, "my_cool_theme", which colors the cursor blue, and the cursor line yellow. Our theme will also syntax highlight strings as red, and comments as magenta.

from rich.style import Style
from textual.widgets.text_area import TextAreaTheme
# ...
my_theme = TextAreaTheme(
    # This name will be used to refer to the theme...
    name="my_cool_theme",
    # Basic styles such as background, cursor, selection, gutter, etc...
    cursor_style=Style(color="white", bgcolor="blue"),
    cursor_line_style=Style(bgcolor="yellow"),
    # `syntax_styles` is for syntax highlighting.
    # It maps tokens parsed from the document to Rich styles.
    syntax_styles={
        "string": Style(color="red"),
        "comment": Style(color="magenta"),
    }
)

Attributes like cursor_style and cursor_line_style apply general language-agnostic styling to the widget. If you choose not to supply a value for one of these attributes, it will be taken from the CSS component styles.

The syntax_styles attribute of TextAreaTheme is used for syntax highlighting and depends on the language currently in use. For more details, see syntax highlighting.

If you wish to build on an existing theme, you can obtain a reference to it using the TextAreaTheme.get_builtin_theme classmethod:

from textual.widgets.text_area import TextAreaTheme

monokai = TextAreaTheme.get_builtin_theme("monokai")

2. Registering a theme¶

Our theme can now be registered with the TextArea instance.

text_area.register_theme(my_theme)

After registering a theme, it'll appear in the available_themes:

>>> print(text_area.available_themes)
{'dracula', 'github_light', 'monokai', 'vscode_dark', 'my_cool_theme'}

We can now switch to it:

text_area.theme = "my_cool_theme"

This immediately updates the appearance of the TextArea:

Tab and Escape behavior¶

Pressing the Tab key will shift focus to the next widget in your application by default. This matches how other widgets work in Textual.

To have Tab insert a \t character, set the tab_behavior attribute to the string value "indent". While in this mode, you can shift focus by pressing the Esc key.

Indentation¶

The character(s) inserted when you press tab is controlled by setting the indent_type attribute to either tabs or spaces.

If indent_type == "spaces", pressing Tab will insert up to indent_width spaces in order to align with the next tab stop.

Undo and redo¶

TextArea offers undo and redo methods. By default, undo is bound to Ctrl+Z and redo to Ctrl+Y.

The TextArea uses a heuristic to place checkpoints after certain types of edit. When you call undo, all of the edits between now and the most recent checkpoint are reverted. You can manually add a checkpoint by calling the TextArea.history.checkpoint() instance method.

The undo and redo history uses a stack-based system, where a single item on the stack represents a single checkpoint. In memory-constrained environments, you may wish to reduce the maximum number of checkpoints that can exist. You can do this by passing the max_checkpoints argument to the TextArea constructor.

Read-only mode¶

TextArea.read_only is a boolean reactive attribute which, if True, will prevent users from modifying content in the TextArea.

While read_only=True, you can still modify the content programmatically.

While this mode is active, the TextArea receives the -read-only CSS class, which you can use to supply custom styles for read-only mode.

Line separators¶

When content is loaded into TextArea, the content is scanned from beginning to end and the first occurrence of a line separator is recorded.

This separator will then be used when content is later read from the TextArea via the text property. The TextArea widget does not support exporting text which contains mixed line endings.

Similarly, newline characters pasted into the TextArea will be converted.

You can check the line separator of the current document by inspecting TextArea.document.newline:

>>> text_area = TextArea()
>>> text_area.document.newline
'\n'

Line numbers¶

The gutter (column on the left containing line numbers) can be toggled by setting the show_line_numbers attribute to True or False.

Setting this attribute will immediately repaint the TextArea to reflect the new value.

You can also change the start line number (the topmost line number in the gutter) by setting the line_number_start reactive attribute.

Extending TextArea¶

Sometimes, you may wish to subclass TextArea to add some extra functionality. In this section, we'll briefly explore how we can extend the widget to achieve common goals.

Hooking into key presses¶

You may wish to hook into certain key presses to inject some functionality. This can be done by over-riding _on_key and adding the required functionality.

Example - closing parentheses automatically¶

Let's extend TextArea to add a feature which automatically closes parentheses and moves the cursor to a sensible location.

from textual import events
from textual.app import App, ComposeResult
from textual.widgets import TextArea


class ExtendedTextArea(TextArea):
    """A subclass of TextArea with parenthesis-closing functionality."""

    def _on_key(self, event: events.Key) -> None:
        if event.character == "(":
            self.insert("()")
            self.move_cursor_relative(columns=-1)
            event.prevent_default()


class TextAreaKeyPressHook(App):
    def compose(self) -> ComposeResult:
        yield ExtendedTextArea.code_editor(language="python")


app = TextAreaKeyPressHook()
if __name__ == "__main__":
    app.run()

This intercepts the key handler when "(" is pressed, and inserts "()" instead. It then moves the cursor so that it lands between the open and closing parentheses.

Typing "def hello(" into the TextArea now results in the bracket automatically being closed:

Advanced concepts¶

Syntax highlighting¶

Syntax highlighting inside the TextArea is powered by a library called tree-sitter.

Each time you update the document in a TextArea, an internal syntax tree is updated. This tree is frequently queried to find location ranges relevant to syntax highlighting. We give these ranges names, and ultimately map them to Rich styles inside TextAreaTheme.syntax_styles.

To illustrate how this works, lets look at how the "Monokai" TextAreaTheme highlights Markdown files.

When the language attribute is set to "markdown", a highlight query similar to the one below is used (trimmed for brevity).

(heading_content) @heading
(link) @link

This highlight query maps heading_content nodes returned by the Markdown parser to the name @heading, and link nodes to the name @link.

Inside our TextAreaTheme.syntax_styles dict, we can map the name @heading to a Rich style. Here's a snippet from the "Monokai" theme which does just that:

TextAreaTheme(
    name="monokai",
    base_style=Style(color="#f8f8f2", bgcolor="#272822"),
    gutter_style=Style(color="#90908a", bgcolor="#272822"),
    # ...
    syntax_styles={
        # Colorise @heading and make them bold
        "heading": Style(color="#F92672", bold=True),
        # Colorise and underline @link
        "link": Style(color="#66D9EF", underline=True),
        # ...
    },
)

To understand which names can be mapped inside syntax_styles, we recommend looking at the existing themes and highlighting queries (.scm files) in the Textual repository.

Adding support for custom languages¶

To add support for a language to a TextArea, use the register_language method.

To register a language, we require two things:

1. A tree-sitter Language object which contains the grammar for the language.
2. A highlight query which is used for syntax highlighting.

Example - adding Java support¶

The easiest way to obtain a Language object is using the py-tree-sitter-languages package. Here's how we can use this package to obtain a reference to a Language object representing Java:

from tree_sitter_languages import get_language
java_language = get_language("java")

The exact version of the parser used when you call get_language can be checked via the repos.txt file in the version of py-tree-sitter-languages you're using. This file contains links to the GitHub repos and commit hashes of the tree-sitter parsers. In these repos you can often find pre-made highlight queries at queries/highlights.scm, and a file showing all the available node types which can be used in highlight queries at src/node-types.json.

Since we're adding support for Java, lets grab the Java highlight query from the repo by following these steps:

1. Open repos.txt file from the py-tree-sitter-languages repo.
2. Find the link corresponding to tree-sitter-java and go to the repo on GitHub (you may also need to go to the specific commit referenced in repos.txt).
3. Go to queries/highlights.scm to see the example highlight query for Java.

Be sure to check the license in the repo to ensure it can be freely copied.

We now have our Language and our highlight query, so we can register Java as a language.

from pathlib import Path

from tree_sitter_languages import get_language

from textual.app import App, ComposeResult
from textual.widgets import TextArea

java_language = get_language("java")
java_highlight_query = (Path(__file__).parent / "java_highlights.scm").read_text()
java_code = """\
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
"""


class TextAreaCustomLanguage(App):
    def compose(self) -> ComposeResult:
        text_area = TextArea.code_editor(text=java_code)
        text_area.cursor_blink = False

        # Register the Java language and highlight query
        text_area.register_language(java_language, java_highlight_query)

        # Switch to Java
        text_area.language = "java"
        yield text_area


app = TextAreaCustomLanguage()
if __name__ == "__main__":
    app.run()

Running our app, we can see that the Java code is highlighted. We can freely edit the text, and the syntax highlighting will update immediately.

Recall that we map names (like @heading) from the tree-sitter highlight query to Rich style objects inside the TextAreaTheme.syntax_styles dictionary. If you notice some highlights are missing after registering a language, the issue may be:

1. The current TextAreaTheme doesn't contain a mapping for the name in the highlight query. Adding a new key-value pair to syntax_styles should resolve the issue.
2. The highlight query doesn't assign a name to the pattern you expect to be highlighted. In this case you'll need to update the highlight query to assign to the name.

Navigation and wrapping information¶

If you're building functionality on top of TextArea, it may be useful to inspect the navigator and wrapped_document attributes.

• navigator is a DocumentNavigator instance which can give us general information about the cursor's location within a document, as well as where the cursor will move to when certain actions are performed.
• wrapped_document is a WrappedDocument instance which can be used to convert document locations to visual locations, taking wrapping into account. It also offers a variety of other convenience methods and properties.

A detailed view of these classes is out of scope, but do note that a lot of the functionality of TextArea exists within them, so inspecting them could be worthwhile.

Reactive attributes¶

Messages¶

• TextArea.Changed
• TextArea.SelectionChanged

Bindings¶

The TextArea widget defines the following bindings:

Component classes¶

The TextArea defines component classes that can style various aspects of the widget. Styles from the theme attribute take priority.

See also¶

• Input - single-line text input widget
• TextAreaTheme - theming the TextArea
• DocumentNavigator - guides cursor movement
• WrappedDocument - manages wrapping the document
• EditHistory - manages the undo stack
• The tree-sitter documentation website.
• The tree-sitter Python bindings repository.
• py-tree-sitter-languages repository (provides binary wheels for a large variety of tree-sitter languages).

Additional notes¶

• To remove the outline effect when the TextArea is focused, you can set border: none; padding: 0; in your CSS.

BINDINGS = [
    Binding("up", "cursor_up", "Cursor up", show=False),
    Binding(
        "down", "cursor_down", "Cursor down", show=False
    ),
    Binding(
        "left", "cursor_left", "Cursor left", show=False
    ),
    Binding(
        "right", "cursor_right", "Cursor right", show=False
    ),
    Binding(
        "ctrl+left",
        "cursor_word_left",
        "Cursor word left",
        show=False,
    ),
    Binding(
        "ctrl+right",
        "cursor_word_right",
        "Cursor word right",
        show=False,
    ),
    Binding(
        "home,ctrl+a",
        "cursor_line_start",
        "Cursor line start",
        show=False,
    ),
    Binding(
        "end,ctrl+e",
        "cursor_line_end",
        "Cursor line end",
        show=False,
    ),
    Binding(
        "pageup",
        "cursor_page_up",
        "Cursor page up",
        show=False,
    ),
    Binding(
        "pagedown",
        "cursor_page_down",
        "Cursor page down",
        show=False,
    ),
    Binding(
        "ctrl+shift+left",
        "cursor_word_left(True)",
        "Cursor left word select",
        show=False,
    ),
    Binding(
        "ctrl+shift+right",
        "cursor_word_right(True)",
        "Cursor right word select",
        show=False,
    ),
    Binding(
        "shift+home",
        "cursor_line_start(True)",
        "Cursor line start select",
        show=False,
    ),
    Binding(
        "shift+end",
        "cursor_line_end(True)",
        "Cursor line end select",
        show=False,
    ),
    Binding(
        "shift+up",
        "cursor_up(True)",
        "Cursor up select",
        show=False,
    ),
    Binding(
        "shift+down",
        "cursor_down(True)",
        "Cursor down select",
        show=False,
    ),
    Binding(
        "shift+left",
        "cursor_left(True)",
        "Cursor left select",
        show=False,
    ),
    Binding(
        "shift+right",
        "cursor_right(True)",
        "Cursor right select",
        show=False,
    ),
    Binding("f6", "select_line", "Select line", show=False),
    Binding("f7", "select_all", "Select all", show=False),
    Binding(
        "backspace",
        "delete_left",
        "Delete character left",
        show=False,
    ),
    Binding(
        "ctrl+w",
        "delete_word_left",
        "Delete left to start of word",
        show=False,
    ),
    Binding(
        "delete,ctrl+d",
        "delete_right",
        "Delete character right",
        show=False,
    ),
    Binding(
        "ctrl+f",
        "delete_word_right",
        "Delete right to start of word",
        show=False,
    ),
    Binding(
        "ctrl+x", "delete_line", "Delete line", show=False
    ),
    Binding(
        "ctrl+u",
        "delete_to_start_of_line",
        "Delete to line start",
        show=False,
    ),
    Binding(
        "ctrl+k",
        "delete_to_end_of_line_or_delete_line",
        "Delete to line end",
        show=False,
    ),
    Binding("ctrl+z", "undo", "Undo", show=False),
    Binding("ctrl+y", "redo", "Redo", show=False),
]

COMPONENT_CLASSES = {
    "text-area--cursor",
    "text-area--gutter",
    "text-area--cursor-gutter",
    "text-area--cursor-line",
    "text-area--selection",
    "text-area--matching-bracket",
}

available_languages

available_themes

cursor_at_end_of_line

cursor_at_end_of_text

cursor_at_first_line

cursor_at_last_line

cursor_at_start_of_line

cursor_at_start_of_text

cursor_blink = reactive(True, init=False)

cursor_location

cursor_screen_offset

document = Document(text)

gutter_width

history = EditHistory(
    max_checkpoints=max_checkpoints,
    checkpoint_timer=2.0,
    checkpoint_max_characters=100,
)

indent_type = 'spaces'

indent_width = reactive(4, init=False)

is_syntax_aware

language = language

line_number_start = reactive(1, init=False)

match_cursor_bracket = reactive(True, init=False)

matching_bracket_location

navigator = DocumentNavigator(wrapped_document)

read_only = reactive(False)

selected_text

selection = reactive(
    Selection(), init=False, always_update=True
)

show_line_numbers = reactive(False, init=False)

soft_wrap = reactive(True, init=False)

text

theme = theme

wrap_width

wrapped_document = WrappedDocument(document)

Changed(text_area)

control

text_area

SelectionChanged(selection, text_area)

selection

text_area

action_cursor_down(select=False)

action_cursor_left(select=False)

action_cursor_line_end(select=False)

action_cursor_line_start(select=False)

action_cursor_page_down()

action_cursor_page_up()

action_cursor_right(select=False)

action_cursor_up(select=False)

action_cursor_word_left(select=False)

action_cursor_word_right(select=False)

action_delete_left()

action_delete_line()

action_delete_right()

action_delete_to_end_of_line()

action_delete_to_end_of_line_or_delete_line()

action_delete_to_start_of_line()

action_delete_word_left()

action_delete_word_right()

action_redo()

action_select_all()

action_select_line()

action_undo()

cell_width_to_column_index(cell_width, row_index)

check_consume_key(key, character=None)

clamp_visitable(location)

clear()

code_editor(
    text="",
    *,
    language=None,
    theme="monokai",
    soft_wrap=False,
    tab_behavior="indent",
    read_only=False,
    show_line_numbers=True,
    line_number_start=1,
    max_checkpoints=50,
    name=None,
    id=None,
    classes=None,
    disabled=False,
    tooltip=None
)

delete(start, end, *, maintain_selection_offset=True)

edit(edit)

find_matching_bracket(bracket, search_from)

get_column_width(row, column)

get_cursor_down_location()

get_cursor_left_location()

get_cursor_line_end_location()

get_cursor_line_start_location(smart_home=False)

get_cursor_right_location()

get_cursor_up_location()

get_cursor_word_left_location()

get_cursor_word_right_location()

get_line(line_index)

get_target_document_location(event)

get_text_range(start, end)

insert(
    text, location=None, *, maintain_selection_offset=True
)

load_text(text)

move_cursor(
    location, select=False, center=False, record_width=True
)

move_cursor_relative(
    rows=0,
    columns=0,
    select=False,
    center=False,
    record_width=True,
)

record_cursor_width()

redo()

register_language(language, highlight_query)

register_theme(theme)

replace(
    insert, start, end, *, maintain_selection_offset=True
)

scroll_cursor_visible(center=False, animate=False)

select_all()

select_line(index)

undo()

Highlight = Tuple[StartColumn, EndColumn, HighlightName]

Location = Tuple[int, int]

Document(text)

end

line_count

lines

newline

start

text

get_index_from_location(location)

get_line(index)

get_location_from_index(index)

get_size(tab_width)

get_text_range(start, end)

replace_range(start, end, text)

end

line_count

lines

newline

start

text

get_line(index)

get_size(indent_width)

get_text_range(start, end)

query_syntax_tree(query, start_point=None, end_point=None)

replace_range(start, end, text)

DocumentNavigator(wrapped_document)

last_x_offset = 0

clamp_reachable(location)

get_location_above(location)

get_location_at_y_offset(location, vertical_offset)

get_location_below(location)

get_location_end(location)

get_location_home(location, smart_home=False)

get_location_left(location)