;
};
Tags are concise elements that let users input information, make selections, filter content, or initiate actions within a user interface. Use them to label items with keywords or categories so content is easier to find, organize, and manage.
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.
The default tag includes a text label, which is mandatory. Labels should be succinct and clearly communicate their purpose.
An optional icon may be positioned to the left of the tag label to provide extra context or emphasis.
A removable tag allows users to selectively manage or remove items as needed, making it useful in dynamic filtering and selection flows.
A removable tag can also include a leading icon when users need both quick visual context and the ability to clear the tag.
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
A tag can include a text label, optional prefix content, and an optional close action when removable. The text remains the primary communicator.
| 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.
Start by deciding whether the tag is informational, clickable, or removable. Each behavior changes what users expect when they interact with it.
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.
Prefer neutral tags by default. Add color only when it helps people distinguish categories, states, or selected values faster.
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.
Tag`}>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Tag
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
Tag
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
Tag
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Tag
```
### Size
Adjust the `size` attribute to customize the tag's dimensions and support a clearer visual hierarchy.
Extra small
SmallMedium
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Extra smallSmallMedium
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
<>
Extra smallSmallMedium
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
Extra smallSmallMedium
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Extra smallSmallMedium
```
### Clickable
Apply the `clickable` attribute for interactive tags that can trigger actions or toggle selection.
Tag
Tag
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
TagTag
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
<>
TagTag
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
TagTag
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
TagTag
```
### Disabled
Apply `disabled` alongside `clickable` when a tag action is temporarily unavailable. The `disabled` attribute has no effect on informational or removable tags.
Enabled
Disabled
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
EnabledDisabled
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
<>
EnabledDisabled
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
EnabledDisabled
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
EnabledDisabled
```
## Options
### Color - filled
Use filled colored tags when you want a stronger visual distinction for categories or states.
Success
InfoErrorWarningGray
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
SuccessInfoErrorWarningGray
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
SuccessInfoErrorWarningGray
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
SuccessInfoErrorWarningGray
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
SuccessInfoErrorWarningGray
```
### Color - outline
Use `variant="outline"` when you want a subtler visual distinction without a filled surface.
Success
InfoErrorWarningGray
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
SuccessInfoErrorWarningGray
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
SuccessInfoErrorWarningGray
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
SuccessInfoErrorWarningGray
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
SuccessInfoErrorWarningGray
```
### Removable - filled
Enable `removable` when users need to clear selected items, applied filters, or entered values.
Default
SuccessInfoErrorWarningGray
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
DefaultSuccessInfoErrorWarningGray
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
DefaultSuccessInfoErrorWarningGray
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
DefaultSuccessInfoErrorWarningGray
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
DefaultSuccessInfoErrorWarningGray
```
### Removable - outline
Use `variant="outline"` with `removable` when you want the same close behavior with lower visual weight.
Default
SuccessInfoErrorWarningGray
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
DefaultSuccessInfoErrorWarningGray
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqTag } from "@beeq/react";
DefaultSuccessInfoErrorWarningGray
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag],
template: `
DefaultSuccessInfoErrorWarningGray
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
DefaultSuccessInfoErrorWarningGray
```
### Prefix - filled
Use the `prefix` slot to add an icon when extra context helps, while keeping the text label as the main content.
Default
Success
Info
Error
Warning
Gray
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Default
Success
Info
Error
Warning
Gray
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTag } from "@beeq/react";
Default
Success
Info
Error
Warning
Gray
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag, BqIcon } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag, BqIcon],
template: `
Default
Success
Info
Error
Warning
Gray
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Default
Success
Info
Error
Warning
Gray
```
### Prefix - outline
Use the outline variant with a prefix icon when you want context with a lighter visual treatment.
Default
Success
Info
Error
Warning
Gray
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Default
Success
Info
Error
Warning
Gray
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTag } from "@beeq/react";
Default
Success
Info
Error
Warning
Gray
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqTag, BqIcon } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqTag, BqIcon],
template: `
Default
Success
Info
Error
Warning
Gray
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Default
Success
Info
Error
Warning
Gray
```
## Best practices
Do
Position tags where they remain visible and accessible without obstructing important content or interactions.
Don't
Don't use sentence-length labels or dense technical wording inside tags.
Do
Use visually distinct styles and colors to differentiate types of tags when those distinctions help users.
Don't
Don't rely on an icon alone. A tag still needs a clear text label.
Do
Make interactive tags easy to use, whether the goal is to click, toggle, or remove them.
Don't
Don'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.
Do
Group tags in a meaningful set when they work as filters, suggestions, or applied selections so users can compare them quickly.
Don't
Don'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.
Do
Reserve removable tags for low-stakes selections like applied filters or entered keywords, where removing the tag is easy to undo.
Don't
Don'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.
The `disabled` prop only takes effect when `clickable` is also set. Disabling an informational or removable tag has no visual or behavioral impact.
## Accessibility
* Built in: when a tag is clickable, the component renders a native `button` in the shadow DOM, not a generic `div`, so keyboard and button semantics work by default.
* Built in: when a clickable tag is disabled, the internal button receives `disabled` and no click, focus, or blur behavior is emitted.
* Built in: when a removable tag is closed, the host reflects `hidden` and `aria-hidden`, and the close action is exposed through a button labeled `Close`.
* 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` |
| `bqClick` | Fires when the tag is clicked | `CustomEvent` |
| `bqClose` | Fires when a removable tag is closed and hidden | `CustomEvent` |
| `bqFocus` | Fires when the tag receives focus | `CustomEvent` |
| `bqOpen` | Fires when a removable tag is shown again | `CustomEvent` |
* 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 on `bqClick`, `bqClose`, and `bqOpen`. 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` |
| `show()` | Programmatically shows a removable tag again | `show() => Promise` |
### 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
| Variable | Description | Default |
| ------------------------------- | ----------------------------- | ----------------------------------------------------------- |
| `--bq-tag--background-color` | Tag background color | `var(--bq-ui--secondary)` |
| `--bq-tag--border-color` | Tag border color | `transparent` |
| `--bq-tag--border-radius` | Tag border radius | `var(--bq-radius--s)` |
| `--bq-tag--border-style` | Tag border style | `solid` |
| `--bq-tag--border-width` | Tag border width | `var(--bq-stroke-s)` |
| `--bq-tag--small-border-radius` | Small tag border radius | `var(--bq-radius--xs)` |
| `--bq-tag--small-gap` | Small tag content gap | `var(--bq-spacing-xs2)` |
| `--bq-tag--small-padding-x` | Small tag horizontal padding | `calc(var(--bq-spacing-xs) - var(--bq-tag--border-width))` |
| `--bq-tag--small-padding-y` | Small tag vertical padding | `calc(var(--bq-spacing-xs3) - var(--bq-tag--border-width))` |
| `--bq-tag--medium-gap` | Medium tag content gap | `var(--bq-spacing-xs)` |
| `--bq-tag--medium-padding-x` | Medium tag horizontal padding | `calc(var(--bq-spacing-s) - var(--bq-tag--border-width))` |
| `--bq-tag--medium-padding-y` | Medium tag vertical padding | `calc(var(--bq-spacing-xs2) - var(--bq-tag--border-width))` |
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore tag variants and behaviors in Storybook
View the component source on GitHub
Tags are concise elements that let users input information, make selections, filter content, or initiate actions within a user interface. Use them to label items with keywords or categories so content is easier to find, organize, and manage.
A tag can include a text label, optional prefix content, and an optional close action when removable. The text remains the primary communicator.
| 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.