Tags can be purely informational, clickable, or removable. Icons can support the meaning of a tag, but they cannot replace the text label as the only content.
When to use
Use tags when
- You need to label or categorize items, content, or metadata
- Users should be able to scan keywords, categories, or attributes quickly
- The UI needs compact filters, suggestion chips, or removable selections
- A short, structured label is enough to communicate the meaning
Do not use tags when
- The content requires long explanations or sentence-length text
- The information would be clearer as a button, badge, or full filter panel
- The tag would obstruct important content or crowd the layout
- The meaning depends on an icon alone without a readable text label
Patterns
The design guidance highlights several common ways tags can appear in an interface.Default
The default tag includes a text label, which is mandatory. Labels should be succinct and clearly communicate their purpose.
Default with icon
An optional icon may be positioned to the left of the tag label to provide extra context or emphasis.
Removable
A removable tag allows users to selectively manage or remove items as needed, making it useful in dynamic filtering and selection flows.
Removable with icon
A removable tag can also include a leading icon when users need both quick visual context and the ability to clear the tag.
Colored
A colored tag helps highlight or differentiate categories, types, or states within an interface.
Tags serve four functional roles: input (user-entered keywords or values), suggestion (pre-defined hints offered based on context), filter (applied search or browse criteria shown as chips), and assist (read-only context chips alongside content). Choose the visual pattern — informational, clickable, or removable — to match the functional role.
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Wrapper | The main visual container of the tag |
| 2 | Prefix | Optional icon or content placed before the text |
| 3 | Text | The visible label of the tag |
| 4 | Close button | Optional action used to remove the tag |
Design guidelines
Use tags with restraint so they help users scan and act without turning into visual noise.Choose the role
Start by deciding whether the tag is informational, clickable, or removable. Each behavior changes what users expect when they interact with it.
Choose the size
Use
medium tags when the label needs more prominence, small for secondary metadata, and xsmall only when space is tight and the text can stay readable.Keep tag labels short, ideally one or two words or roughly no more than 20 characters, so the tag remains scannable.
Usage
Default
Use the standard tag when you want a simple and clean representation.Size
Adjust thesize attribute to customize the tag’s dimensions and support a clearer visual hierarchy.
Clickable
Apply theclickable attribute for interactive tags that can trigger actions or toggle selection.
Disabled
Applydisabled alongside clickable when a tag action is temporarily unavailable. The disabled attribute has no effect on informational or removable tags.
Options
Color - filled
Use filled colored tags when you want a stronger visual distinction for categories or states.Color - outline
Usevariant="outline" when you want a subtler visual distinction without a filled surface.
Removable - filled
Enableremovable when users need to clear selected items, applied filters, or entered values.
Removable - outline
Usevariant="outline" with removable when you want the same close behavior with lower visual weight.
Prefix - filled
Use theprefix slot to add an icon when extra context helps, while keeping the text label as the main content.
Prefix - outline
Use the outline variant with a prefix icon when you want context with a lighter visual treatment.Best practices
DoPosition tags where they remain visible and accessible without obstructing important content or interactions.
Don’tDon’t use sentence-length labels or dense technical wording inside tags.
DoUse visually distinct styles and colors to differentiate types of tags when those distinctions help users.
Don’tDon’t rely on an icon alone. A tag still needs a clear text label.
DoMake interactive tags easy to use, whether the goal is to click, toggle, or remove them.
Don’tDon’t mix too many colors or tag styles in the same area. Limit color use to a single semantic purpose — more than one color scheme in a single list forces users to decode two systems at once.
DoGroup tags in a meaningful set when they work as filters, suggestions, or applied selections so users can compare them quickly.
Don’tDon’t display a single standalone tag. Tags gain meaning through comparison — use a set of at least three before reaching for this component, otherwise a plain label or a different component will communicate the same thing more clearly.
DoReserve removable tags for low-stakes selections like applied filters or entered keywords, where removing the tag is easy to undo.
Don’tDon’t use removable tags for critical or destructive actions. A close button is easy to tap accidentally — use an explicit button or a confirmation dialog for consequential operations.
Accessibility
- Built in: when a tag is clickable, the component renders a native
buttonin the shadow DOM, not a genericdiv, so keyboard and button semantics work by default. - Built in: when a clickable tag is disabled, the internal button receives
disabledand no click, focus, or blur behavior is emitted. - Built in: when a removable tag is closed, the host reflects
hiddenandaria-hidden, and the close action is exposed through a button labeledClose. - Built in: decorative close icons are marked
aria-hidden="true"so assistive technology reads the button label instead of the icon name. - You must: keep text as the primary content. Prefix icons can reinforce meaning, but they should never replace the visible label.
- You must: avoid relying on color alone for category or state. The label should still make sense without the visual treatment.
- You must: make the effect of removing a tag obvious in the surrounding UI, especially in filters and selected-value patterns.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
border | border | The corner radius of the Tag (will override size’s predefined border) | 'none' | 'xs2' | 'xs' | 's' | 'm' | 'l' | 'full' | undefined |
clickable | clickable | If true, the Tag can be clickable | boolean | false |
color | color | The color style of the Tag | 'error' | 'gray' | 'info' | 'success' | 'warning' | undefined |
disabled | disabled | If true, the Tag will be disabled (only if clickable) | boolean | false |
hidden | hidden | If true, the Tag component will be hidden | boolean | undefined |
removable | removable | If true, the Tag component can be removed | boolean | false |
selected | selected | If true, the Tag is selected (only if clickable) | boolean | false |
size | size | The size of the Tag component | 'xsmall' | 'small' | 'medium' | 'medium' |
variant | variant | The visual variant of the Tag | 'filled' | 'outline' | 'filled' |
Events
| Event | Description | Type |
|---|---|---|
bqBlur | Fires when the tag loses focus | CustomEvent<HTMLBqTagElement> |
bqClick | Fires when the tag is clicked | CustomEvent<HTMLBqTagElement> |
bqClose | Fires when a removable tag is closed and hidden | CustomEvent<HTMLBqTagElement> |
bqFocus | Fires when the tag receives focus | CustomEvent<HTMLBqTagElement> |
bqOpen | Fires when a removable tag is shown again | CustomEvent<HTMLBqTagElement> |
- In React, prefix events with
on:onBqBlur,onBqClick,onBqClose,onBqFocus,onBqOpen. - In Angular, use the event binding syntax:
(bqBlur),(bqClick),(bqClose),(bqFocus),(bqOpen). - In Vue, use the
@shorthand with camelCase:@bqBlur,@bqClick,@bqClose,@bqFocus,@bqOpen. preventDefault()is supported onbqClick,bqClose, andbqOpen. Calling it cancels the default toggle, hide, or show behavior after the event fires.
Methods
| Method | Description | Signature |
|---|---|---|
hide() | Programmatically hides a removable tag | hide() => Promise<void> |
show() | Programmatically shows a removable tag again | show() => Promise<void> |
Slots
| Slot | Description |
|---|---|
| (default) | The text content of the tag |
prefix | Content displayed before the text |
Shadow parts
| Part | Description |
|---|---|
wrapper | The wrapper container inside the shadow DOM |
prefix | The prefix container when icon content exists |
text | The element containing the tag text |
btn-close | The close button used to remove the tag |
CSS custom properties
Resources
Interactive playground
Explore tag variants and behaviors in Storybook
Source code
View the component source on GitHub