Frequently Asked Questions

Does Textual support images?
How can I fix ImportError cannot import name ComposeResult from textual.app ?
How can I select and copy text in a Textual app?
How do I center a widget in a screen?
How do I pass arguments to an app?
Why doesn't Textual look good on macOS?
Why doesn't Textual support ANSI themes?

Does Textual support images?

Textual doesn't have built in support for images yet, but it is on the Roadmap.

See also the rich-pixels project for a Rich renderable for images that works with Textual.

How can I fix ImportError cannot import name ComposeResult from textual.app ?

You likely have an older version of Textual. You can install the latest version by adding the -U switch which will force pip to upgrade.

The following should do it:

pip install "textual[dev]" -U

How can I select and copy text in a Textual app?

Running a Textual app puts your terminal in to application mode which disables clicking and dragging to select text. Most terminal emulators offer a modifier key which you can hold while you click and drag to restore the behavior you may expect from the command line. The exact modifier key depends on the terminal and platform you are running on.

iTerm Hold the OPTION key.
Gnome Terminal Hold the SHIFT key.
Windows Terminal Hold the SHIFT key.

Refer to the documentation for your terminal emulator, if it is not listed above.

To center a widget within a container use align. But remember that align works on the children of a container, it isn't something you use on the child you want centered.

For example, here's an app that shows a Button in the middle of a Screen:

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

class ButtonApp(App):

    CSS = """
    Screen {
        align: center middle;
    }
    """

    def compose(self) -> ComposeResult:
        yield Button("PUSH ME!")

if __name__ == "__main__":
    ButtonApp().run()

How do I pass arguments to an app?

When creating your App class, override __init__ as you would when inheriting normally. For example:

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

class Greetings(App[None]):

    def __init__(self, greeting: str="Hello", to_greet: str="World") -> None:
        self.greeting = greeting
        self.to_greet = to_greet
        super().__init__()

    def compose(self) -> ComposeResult:
        yield Static(f"{self.greeting}, {self.to_greet}")

Then the app can be run, passing in various arguments; for example:

# Running with default arguments.
Greetings().run()

# Running with a keyword arguyment.
Greetings(to_greet="davep").run()

# Running with both positional arguments.
Greetings("Well hello", "there").run()

Why doesn't Textual look good on macOS?

The default macOS Terminal.app is getting rather old now, and has problems such as being limited to just 256 colors. We recommend installing a newer terminal such as iTerm2, Kitty or WezTerm.

Why doesn't Textual support ANSI themes?

Textual will not generate escape sequences for the 16 themeable ANSI colors.

This is an intentional design decision we took for for the following reasons:

Not everyone has a carefully chosen ANSI color theme. Color combinations which may look fine on your system, may be unreadable on another machine. There is very little an app author or Textual can do to resolve this. Asking users to simply pick a better theme is not a good solution, since not all users will know how.
ANSI colors can't be manipulated in the way Textual can do with other colors. Textual can blend colors and produce light and dark shades from an original color, which is used to create more readable text and user interfaces. Color blending will also be used to power future accessibility features.

Textual has a design system which guarantees apps will be readable on all platforms and terminals, and produces better results than ANSI colors.

There is currently a light and dark version of the design system, but more are planned. It will also be possible for users to customize the source colors on a per-app or per-system basis. This means that in the future you will be able to modify the core colors to blend in with your chosen terminal theme.

Generated by FAQtory

5.4 KiB Raw Blame History