Textual Textarea

Textual Textarea Screenshot

Note: This is NOT the official TextArea widget!

With v0.38.0, Textual added a built-in TextArea widget. You probably want to use that widget instead of this one. This project predated the official widget; versions < v0.8.0 had a completely separate implmentation.

Since v0.8.0, this project uses the built-in TextArea widget, but adds the features outlined below.

Installation

pip install textual-textarea

Features

Full-featured text editor experience with VS-Code-like bindings, in your Textual App:

  • Syntax highlighting and support for Pygments themes.
  • Move cursor and scroll with mouse or keys (including ctrl+arrow, PgUp/Dn, ctrl+Home/End).
  • Open (ctrl+o) and save (ctrl+s) files.
  • Cut (ctrl+x), copy (ctrl+c), paste (ctrl+u/v), optionally using the system clipboard. On terminals that support the Kitty keyboard protocol, the cmd equivalents work too.
  • Delete a word with ctrl+backspace, alt+backspace, or alt+delete.
  • Comment selections with ctrl+/.
  • Indent and dedent (optionally for a multiline selection) to tab stops with Tab and shift+Tab.
  • Automatic completions of quotes and brackets.
  • Select text by double-, triple-, or quadruple-clicking.
  • Quit with ctrl+q.

Usage

Initializing the Widget

The TextArea is a Textual Widget. You can add it to a Textual app using compose or mount:

from textual_textarea import TextEditor
from textual.app import App, ComposeResult

class TextApp(App, inherit_bindings=False):
    def compose(self) -> ComposeResult:
        yield TextEditor(text="hi", language="python", theme="nord-darker", id="ta")

    def on_mount(self) -> None:
        editor = self.query_one("#id", expect_type=TextEditor)
        editor.focus()

app = TextApp()
app.run()

In addition to the standard Widget arguments, TextArea accepts three additional, optional arguments when initializing the widget:

  • language (str): Must be None or the short name of a Pygments lexer, e.g., python, sql, as3. Defaults to None.
  • theme (str): Must be name of a Pygments style, e.g., bw, github-dark, solarized-light. Defaults to monokai.
  • use_system_clipboard (bool): Set to False to make the TextArea's copy and paste operations ignore the system clipboard. Defaults to True. Some Linux users may need to apt-install xclip or xsel to enable the system clipboard features.

The TextArea supports many actions and key bindings. For proper binding of ctrl+c to the COPY action, you must initialize your App with inherit_bindings=False (as shown above), so that ctrl+c does not quit the app. The TextArea implements ctrl+q as quit; you way wish to mimic that in your app so that other in-focus widgets use the same behavior.

Interacting with the Widget

Getting and Setting Text

The TextArea exposes a text property that contains the full text contained in the widget. You can retrieve or set the text by interacting with this property:

editor = self.query_one(TextEditor)
old_text = editor.text
editor.text = "New Text!\n\nMany Lines!"

Similarly, the TextEditor exposes a selected_text property (read-only):

editor = self.query_one(TextEditor)
selection = editor.selected_text

Inserting Text

You can insert text at the current selection:

editor = self.query_one(TextEditor)
editor.text = "01234"
editor.selection = Selection((0, 2), (0, 2))
editor.insert_text_at_selection("\nabc\n")
assert editor.text == "01\nabc\n234"
assert editor.selection == Selection((2, 0), (2, 0))

Getting and Setting The Cursor Position

The TextEditor exposes a selection property that returns a textual.widgets.text_area.Selection:

editor = self.query_one(TextEditor)
old_selection = editor.selection
editor.selection = Selection((999, 0),(999, 0))  # the cursor will move as close to line 999, pos 0 as possible
cursor_line_number = editor.selection.end[0]
cursor_x_position = editor.selection.end[1]

Getting and Setting The Language

Syntax highlighting and comment insertion depends on the configured language for the TextEditor.

The TextArea exposes a language property that returns None or a string that is equal to the short name of an installed tree-sitter language:

editor = self.query_one(TextEditor)
old_language = editor.language
editor.language = "python"

Getting Theme Colors

If you would like the rest of your app to match the colors from the TextArea's theme, they are exposed via the theme_colors property.

editor = self.query_one(TextEditor)
color = editor.theme_colors.contrast_text_color
bgcolor = editor.theme_colors.bgcolor
highlight = editor.theme_colors.selection_bgcolor

Adding Bindings and other Behavior

You can subclass TextEditor to add your own behavior. This snippet adds an action that posts a Submitted message containing the text of the TextEditor when the user presses ctrl+j:

from textual.message import Message
from textual_textarea import TextEditor


class CodeEditor(TextEditor):
    BINDINGS = [
        ("ctrl+j", "submit", "Run Query"),
    ]

    class Submitted(Message, bubble=True):
        def __init__(self, text: str) -> None:
            super().__init__()
            self.text = text

    async def action_submit(self) -> None:
        self.post_message(self.Submitted(self.text))

Project links

Data verified by PyPI on Aug 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tedconbeer from gravatar.com tedconbeer

Credits

Author: Ted Conbeer

GitHub Statistics

Data verified by PyPI on Aug 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <3.15, >=3.10

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

textual_textarea-0.18.1.tar.gz (28.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

textual_textarea-0.18.1-py3-none-any.whl (27.3 kB view details)

Uploaded Python 3

File details

Details for the file textual_textarea-0.18.1.tar.gz.

File metadata

  • Download URL: textual_textarea-0.18.1.tar.gz
  • Upload date:
  • Size: 28.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for textual_textarea-0.18.1.tar.gz
Algorithm Hash digest
SHA256 9db53da7659883cd905e66eabae11943c5b2e3a7530873ff85ee35d4bc3d928d
MD5 92149f2064c91b776283e678a7c497f4
BLAKE2b-256 5be4aa225ac619c07149b18864a240fd8cc6a710e8ffc01028bafa0059ace893

See more details on using hashes here.

Provenance

The following attestation bundles were made for textual_textarea-0.18.1.tar.gz:

Publisher: publish.yml on tconbeer/textual-textarea

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file textual_textarea-0.18.1-py3-none-any.whl.

File metadata

File hashes

Hashes for textual_textarea-0.18.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a99c072ab38fe667b9486f099d3dae2a99a59ca1f2207c0c143d0d5015cffe8d
MD5 e713a4f50188ca2f4d3f617d75630dee
BLAKE2b-256 ef79b117fd8f78fffffad74a411e9c48883a69bb4dbd8dff720263ec6c9949ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for textual_textarea-0.18.1-py3-none-any.whl:

Publisher: publish.yml on tconbeer/textual-textarea

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.18.1 This release

2 files

0.18.0

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.4

2 files

0.14.3

2 files

0.14.2

2 files

0.14.1

2 files

0.14.0

2 files

0.13.1

2 files

0.13.0

2 files

0.12.0

2 files

0.11.3

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page