Tag Block
The Tag block renders a small colored label — a pill or chip — showing a short piece of text. Its look is driven by four style axes: a Color, a Variant, a Size, and a Shape. You can add a Status Dot, start/end Icons, a Max Width, a Disabled condition, and a Dismissible toggle (X button). Tags are display-first but interactive: wire On Click to make the pill act like a button, or On Dismiss to react when users remove it.
Note: Use Tag when you need a short text marker with color and shape (status, category, count). Use Avatar when you need an image/initials marker, or Button/Icon Button when you need an action control.
Tag — Content Properties
| Property | Type | Default | Description |
| label | string (bindable, translatable) | Tag | The text shown on the tag. Coerced to string if non-string value is bound |
| tooltip | string (bindable, translatable) | — | Hover tooltip text |
| interactions | event list | — | On Click and On Dismiss event handlers |
| permissions | permission rule | — | Restrict who sees the block |
Tag — Appearance Properties
| Property | Type | Default | Description |
| variant | soft | clear | solid | subtle | ghost | outlined | solid | The tag's style family: how the Color turns into fill, border, and text |
| size | "xs" | "sm" | "md" | sm | The tag's height and text size |
| color | named color | fine-tuned object | conditional | brand | Base color from which fill, border, and text are derived. Supports conditional rules for data-driven coloring |
| shape | Square (2px) | Rounded (6px) | Pill (fully rounded) | Rounded | Corner rounding of the chip |
| maxWidth | number (px) | Auto | Maximum pixel width before the label truncates with an ellipsis |
| disabled | condition | — | Greys the tag and stops On Click and On Dismiss from firing |
| decorators.statusDot | boolean | off | A small colored dot before the label, for status indicators |
| decorators.startDecorator | icon name (bindable/conditional) | — | Icon at the start (left) of the label |
| decorators.endDecorator | icon name (bindable/conditional) | — | Icon at the end (right) of the label |
| decorators.dismissible | boolean | off | Adds an X button so users can remove the tag. Required for On Dismiss to fire |
| visibility | conditions | — | Show/hide the block |
| customCSS / htmlAttributes | CSS / attribute map | — | Advanced escape hatches. Appear only once enabled on the block |
Variant Style Guide
| Variant | Visual Description | Typical Use |
| solid | Filled background, matching text | High-emphasis status labels |
| soft | Tinted background, colored text | General-purpose status pills |
| subtle | Tinted background, no border | Low-emphasis markers |
| clear | Transparent background, colored border | Outlined category chips |
| outlined | Border + colored text, no fill | Neutral or structural labels |
| ghost | Dashed border style | Placeholder or pending states |
Tag Events
| Event | Trigger | Available When |
| On Click | User clicks or taps the tag | Always — but does not fire when the tag is disabled |
| On Dismiss | User clicks the X button | Dismissible is on AND the tag is enabled |
Tag — Exposed State
| Binding | Type | Description |
{{ id.content.label }} | string | The tag's label after bindings resolve |
{{ id.content.tooltip }} | string | The resolved tooltip text |
{{ id.appearance.* }} | object | Color, variant, size, shape, maxWidth, disabled, decorators |
Tag Behaviors & Gotchas
Warning: Disabled tag ignores clicks and dismissal: When the Disabled condition is true, On Click and On Dismiss never fire. The pointer/hover affordance is also dropped.
Warning: Dismiss X only shows while Dismissible is on: With Dismissible off, the X button disappears and On Dismiss can never fire (even if a handler is still configured). The On Dismiss row stays visible in the panel when a handler is saved — leave Dismissible on for any tag whose On Dismiss should fire.
Note: Color and Disabled react to your data live: Both accept conditions and re-evaluate as bound data changes. This is the intended way to build status pills that respond to record state.
Note: Fine-tuned colors vs. named colors: A fine-tuned color set paints inline styles for background, border, and text. A plain named color uses the variant's built-in palette. Switching from fine-tuned back to a named color drops your per-channel overrides.
Note: Non-string labels are stringified: Numbers, booleans, objects, and arrays are coerced to their string form before rendering.
Tag — Examples
Text Display — Typography Block Quick Reference
The Typography block (shown as Text in the block picker) is the primary text display component. See Typography & Link for the full reference. Key facts for context:
| Use Case | Block to Use | Why |
| Short status text, category label, count chip | Tag | Built-in color, shape, icon decorators, dismiss button |
| Headings, paragraphs, data-bound descriptions | Typography (Text) | Full typographic control, Markdown/HTML rendering, truncation |
| Clickable text that navigates to a URL | Link | Built-in navigation, underline styles, color scheme |
| Rich formatted content from a database field | Typography (Text) with type = Rich Text or HTML | Renders editor-generated or raw HTML correctly |
Related Blocks
| Block | Relationship |
| Button | Use when you need a labelled action control rather than a status/marker pill |
| Icon Button | An icon-only control — use when there's no text to show |
| Avatar | Use for an image/initials marker instead of a text pill |
| Typography | Use plain text display when the marker needs no color, shape, or icon |
| Link | Use when the text needs to navigate somewhere |
Frequently Asked Questions
How do I set Tag color dynamically based on a status value?
Bind the Color property to a conditional expression, for example: {{ row.status === 'active' ? 'success' : row.status === 'error' ? 'error' : 'neutral' }}. The accepted values are UnifyApps color tokens such as brand, success, warning, error, neutral, and any custom palette keys defined in your theme.
Can a dismissed Tag be shown again later?
A dismissible Tag fires the On Dismiss event when the user clicks its close button, but the block itself does not track dismissed state — it simply emits the event. To hide the tag after dismissal, set a page variable to false in the On Dismiss handler and bind the Tag's Visibility condition to that variable. Set the variable back to true when you want the tag to reappear.
What is the difference between the On Click and On Dismiss events?
On Click fires when the user clicks anywhere on the tag body (the label area). On Dismiss fires only when the user clicks the dismiss (×) button in the end-decorator position. If both are enabled and the user clicks the dismiss button, only On Dismiss fires — it does not also fire On Click.