Tag Group
Tags allow users to categorize content. They can represent keywords or people, and are grouped to describe an item or a search request.
Example
Content
tag_group accepts item elements as children, each with a key prop. Basic usage of tag_group, seen in the example above, shows multiple items populated with a string.
Labeling
To provide a visual label for the tag group, use the label prop.
Label Position
By default, the position of the label is above the tag group, but it can be moved to the side using the label_position prop.
Label Alignment
By default, the label is horizontally aligned to the start of the tag group element, but it can be moved to the end by using the label_align prop.
Events
Removing tags can be enabled by providing the on_remove prop to the tag group, which will receive the set of keys to remove.
Use the prop action_label to display an action button with that label at the end of the tags. The custom action that will be performed is specified by the on_action prop.
Links
Tags can become links to another page or website by passing the href prop to the ui.item component. The target window to open the link in can be configured using the target prop.
Help text
A tag group can have both a description and an error_message. The error message should offer specific guidance on how to correct the input.
The is_invalid prop can be used to set whether the current tag group state is valid or invalid.
Contextual help
Using the contextual_help prop, a ui.contextual_help can be placed next to the label to provide additional information about the tag group.
Limit rows
To limit the number of rows initially shown, use the max_rows prop. A button to allow the user to expand to show all tags will be displayed if the tags would overflow the number of rows.
Empty state
By default the empty state displays the text “None”.
Use the render_empty_state prop to specify the element to be displayed when the tag group will display when no tags are provided.
API reference
A tag group displays a list of keywords to describe an item.
Returns: Element The rendered tag group element.
| Parameters | Type | Default | Description |
|---|---|---|---|
| *children | str | int | float | bool | BaseElement | The tags to render within the tag_group. | |
| action_label | str | None | None | The label for the action button. If provided, an action button will be displayed. |
| render_empty_state | Element | None | None | The element that will be rendered when there is no content to display. |
| max_rows | int | None | None | The maximum amount of rows to show. If provided, will render a button that allows the user to expand the tag group. |
| error_message | None | bool | int | str | Element | List[NodeType] | None | An error message for the field. |
| label | None | bool | int | str | Element | List[NodeType] | None | The label for the tag group. |
| description | None | bool | int | str | Element | List[NodeType] | None | A description for the tag group. |
| label_position | Literal['top', 'side'] | 'top' | The position of the label relative to the input. |
| label_align | Literal['start', 'end'] | None | 'start' | The alignment of the label relative to the input. |
| contextual_help | None | bool | int | str | Element | List[NodeType] | None | A ContextualHelp element to place next to the label. |
| is_invalid | bool | None | None | Whether the tag group is in an invalid state. |
| key | str | None | None | A unique identifier used by React to render elements in a list. |