textual-tags 0.3.1

A custom tags widget to be used in textual applications

textual-tags

This library provides a custom tags widget called Tags, which can be easily added into your existing textual application.

Requires a Nerdfont to render the round corners of the Tag labels.

Features

• Can be initiated with a predefined set/list of tags, similar entries will be ignored
• Consists of a TagInput, with autocompletion powered by textual-autocomplete for existing tags and displayed tags wrapped in a flexbox-like container
• Two different ways to display the tags (with x at the end or without)
• Option to also add new not predefined tags, which are then also available for autocompletion
• vim-like completion control

Installation

textual-tags is hosted on PyPi and can be installed with:

pip install textual-tags

or add it to your project using uv with:

uv add textual-tags

Demo App

You can run the demo app after installation with textual-tags or using uv with:

uvx textual-tags

Usage

Here is an exampke usage of the Tags-widget in a textual App. You can also check the demo app here.

from textual.app import App

from textual_tags import Tags

PRE_DEFINED_TAGS = [
    "uv",
    "Terminal",
    "tcss",
    "Textual",
    "Tags",
    "Widget",
    "Python",
    "TUI",
    "Highlander"
]

class TagsApp(App):
    DEFAULT_CSS = """
    Tags {
        width:50;
    }
    """
    def compose(self):
        yield Tags(
            # list/set of tags to start with
            tag_values=PRE_DEFINED_TAGS,
            # Show Tag-Labels as `TAG x` instead of ' TAG '
            show_x=False,
            # All tags are selected on startup
            start_with_tags_selected=True,
            # Allow to enter custom new tags and dont hide TagInput if all tags are selected
            # Also allows delete/edit of last tag when pressing `backspace` on empty input
            allow_new_tags=False,
        )

def main():
    app = TagsApp()
    app.run()

if __name__ == '__main__':
    main()

Messages

Tags sends two messages:

• Tag.Removed, send when a tag is removed in any way
• Tag.Focused, send when a tag is focused
• Tag.Hovered, send when a tag is hovered
• Tag.Selected, send when a tag is selected
• TagAutoComplete.Applied, send when a completion option is applied

Issues/Feedback

Feel free to reach out and share your feedback, or open an Issue, if something doesnt work as expected. Also check the Changelog for new updates.