SelectTag

Introduction

SelectTag widget in Supervisely is a compact dropdown menu that allows users to select tag metadata from a predefined list of TagMeta objects and create new tags on the fly. It supports features like filtering, multiple selection, and various tag value types (None, Any String, Any Number, One Of). This widget is commonly used in applications that need to work with annotation tags, such as filtering objects by tags, tag mapping, or configuring tagging workflows.

The SelectTag widget includes event handlers for tracking tag selection changes and new tag creation events.

Read this tutorial in developer portal.

Function signature

SelectTag(
        tags: Optional[Union[List[TagMeta], TagMetaCollection]] = [],
        filterable: Optional[bool] = True,
        placeholder: Optional[str] = "Select tag",
        show_add_new_tag: Optional[bool] = True,
        size: Optional[Literal["large", "small", "mini"]] = None,
        multiple: bool = False,
        widget_id: Optional[str] = None,
)

select-tag

Parameters

Parameters	Type	Description
tags	Union[List[TagMeta], TagMetaCollection]	List of TagMeta objects or TagMetaCollection.
filterable	Optional[bool]	Enable search/filter functionality in dropdown.
placeholder	Optional[str]	Placeholder text when no tag is selected.
show_add_new_tag	Optional[bool]	Whether to show button for adding new tags.
size	Optional[Literal["large", "small", "mini"]]	Size of the select dropdown.
multiple	bool	Whether multiple selection is enabled.
widget_id	Optional[str]	Unique widget identifier.

tags

Initial list of TagMeta instances.

type: Union[List[TagMeta], TagMetaCollection]

default value: []

tag_weather = sly.TagMeta("weather", sly.TagValueType.ANY_STRING)
tag_count = sly.TagMeta("count", sly.TagValueType.ANY_NUMBER)

colors = ["red", "green", "blue"]
tag_color = sly.TagMeta("color", sly.TagValueType.ONEOF_STRING, possible_values=colors)

tag_verified = sly.TagMeta("verified", sly.TagValueType.NONE)

tags = [tag_weather, tag_count, tag_color, tag_verified]

select_tag = SelectTag(tags=tags)

filterable

Enable or disable filtering/searching functionality in the dropdown.

type: Optional[bool]

default value: True

select_tag = SelectTag(tags=tags, filterable=True)

placeholder

Set placeholder text shown when no tag is selected.

type: Optional[str]

default value: "Select tag"

select_tag = SelectTag(tags=tags, placeholder="Select a tag")

multiple

Enable multiple tag selection.

type: bool

default value: False

select_tag = SelectTag(tags, multiple=True)

show_add_new_tag

Show or hide the "Add New Tag" button that allows users to create new tags directly from the widget with configurable value types.

type: Optional[bool]

default value: True

select_tag = SelectTag(tags=tags, show_add_new_tag=True)

add new tag button

size

Set the size of the widget.

type: Optional[Literal["large", "small", "mini"]]

default value: None

select_tag = SelectTag(tags=tags, size="small")

Methods and attributes

Attributes and Methods	Description
get_selected_tag()	Get the currently selected TagMeta object(s).
get_value()	Get the currently selected tag name(s).
set_value()	Sets the selected tag by name or list of names.
get_all_tags()	Returns a copy of all available tags.
set()	Updates the list of available tags and refreshes the widget.
@value_changed	Decorator for value change event.
@tag_created	Decorator for new tag creation event.

Mini App Example

You can find this example in our GitHub repository:

supervisely-ecosystem/ui-widgets-demos/selection/027_select_tag/src/main.py

Import libraries

import os
import supervisely as sly
from dotenv import load_dotenv
from supervisely.app.widgets import Card, Container, NotificationBox, SelectTag

Init API client

First, we load environment variables with credentials and init API for communicating with Supervisely Instance:

load_dotenv("local.env")
load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api()

Create tag metadata

# Create some initial tags with different value types
tag_weather = sly.TagMeta("weather", sly.TagValueType.ANY_STRING)
tag_count = sly.TagMeta("count", sly.TagValueType.ANY_NUMBER)

colors = ["red", "green", "blue"]
tag_color = sly.TagMeta("color", sly.TagValueType.ONEOF_STRING, possible_values=colors)

tag_verified = sly.TagMeta("verified", sly.TagValueType.NONE)

tags = [
    tag_weather,
    tag_count,
    tag_color,
    tag_verified,
]

Initialize SelectTag widget

select_tag = SelectTag(
    tags=tags,
    filterable=True,
    placeholder="Select a tag",
    multiple=True,
    show_add_new_tag=True,
)

Create app layout

Prepare a layout for app using Card widget with the content parameter and place widget that we've just created in the Container widget.

notification_box = NotificationBox()

card = Card(
    title="Select Tag",
    content=Container(widgets=[select_tag, notification_box]),
)

layout = Container(widgets=[card])

app = sly.Application(layout=layout)

Handle tag selection changes

@select_tag.value_changed
def on_tag_selected(selected_tags):
    if isinstance(selected_tags, list):
        tag_names = [tag.name for tag in selected_tags]
        notification_box.set(
            title="Tags selected",
            description=f"Selected tags: {', '.join(tag_names)}",
        )
    else:
        notification_box.set(
            title="Tag selected",
            description=f"Selected tag: {selected_tags.name}",
        )

Handle new tag creation

@select_tag.tag_created
def on_tag_created(new_tag: sly.TagMeta):
    notification_box.set(
        title="New tag created",
        description=f"You have created a new tag: {new_tag.name} (type: {new_tag.value_type})",
    )

layout