Demos
How to import
<script setup lang="ts">
import { Tag, TagGroup, SplitTagGroup } from '@fibrous/semi-ui-vue';
</script>
Basic usage
To use this tag, just wrap the content with the <Tag> tag.
It can be turned into a closable label by adding the closable property.
At this time, clicking x to close will emit the close event, and calling preventDefault on the event in the @close handler keeps the tag shown after clicking
Code
<script setup lang="ts">
import { Space, Tag, type TagCloseEvent } from '@fibrous/semi-ui-vue';
const preventClose = (event: TagCloseEvent) => event.preventDefault();
</script>
<template>
<div>
<Space>
<Tag>default tag</Tag>
<Tag closable>Closable Tag</Tag>
<Tag closable @close="preventClose">Closable Tag, Prevent Default</Tag>
</Space>
</div>
</template>Size
Supports two sizes: large and small (default).
Code
<script setup lang="ts">
import { Space, Tag } from '@fibrous/semi-ui-vue';
</script>
<template>
<Space>
<Tag color="light-blue" size="small">small tag</Tag>
<Tag color="cyan" size="large">large tag</Tag>
</Space>
</template>Shape
Supports two Shape: square(default)、circle。
Code
<script setup lang="ts">
import { Space, Tag } from '@fibrous/semi-ui-vue';
</script>
<template>
<Space>
<Tag color="amber" shape="circle" size="small">small circle tag</Tag>
<Tag color="violet" shape="circle" size="large">large circle tag</Tag>
</Space>
</template>Icon
Use the #prefixIcon and #suffixIcon slots to add icons before or after the content.
Code
<script setup lang="ts">
import { IconGithubLogo, IconSemiLogo } from '@fibrous/semi-icons-vue';
import { Space, Tag } from '@fibrous/semi-ui-vue';
</script>
<template>
<Space>
<Tag color="light-blue" shape="circle" size="large">
<template #prefixIcon>
<IconGithubLogo />
</template>
Semi Design
</Tag>
<Tag color="cyan" shape="circle" size="large">
D2C: figma to code in one click
<template #suffixIcon>
<IconSemiLogo />
</template>
</Tag>
</Space>
</template>Color
Tag supports 16 colors including whites from Semi's palette: amber, blue, cyan, green, grey, indigo, light-blue, light-green, lime, orange, pink, purple, red, teal, violet, yellow, white. You can also customize color through style.
Code
<script setup lang="ts">
import { Space, Tag, type TagColor } from '@fibrous/semi-ui-vue';
const colors: TagColor[] = ['amber', 'blue', 'cyan', 'green', 'grey', 'indigo', 'light-blue', 'light-green', 'lime', 'orange', 'pink', 'purple', 'red', 'teal', 'violet', 'yellow', 'white'];
</script>
<template>
<Space wrap>
<Tag v-for="color in colors" :key="color" :color="color">{{ color }}</Tag>
</Space>
</template>AI style - colorful labels
Set colorful to true to get colorful labels.
Code
<script setup lang="ts">
import { IconAIFilledLevel1, IconAIFilledLevel3 } from '@fibrous/semi-icons-vue';
import { Tag } from '@fibrous/semi-ui-vue';
const grid = { display: 'grid', gridTemplateColumns: 'repeat(3,1fr)', gridGap: '10px', width: 'fit-content' };
</script>
<template>
<div :style="{ display: 'flex', flexDirection: 'column', rowGap: '30px' }">
<div :style="grid">
<Tag colorful gradient shape="circle" type="solid">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
<Tag colorful gradient shape="circle" type="light">
<template #prefixIcon>
<IconAIFilledLevel3 size="small" />
</template>
AI
</Tag>
<Tag colorful gradient shape="circle" type="ghost">
<template #prefixIcon>
<IconAIFilledLevel3 size="small" />
</template>
AI
</Tag>
<Tag colorful shape="circle" type="solid">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
<Tag colorful shape="circle" type="light">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
<Tag colorful shape="circle" type="ghost">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
</div>
<div :style="grid">
<Tag colorful gradient type="solid">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
<Tag colorful gradient type="light">
<template #prefixIcon>
<IconAIFilledLevel3 size="small" />
</template>
AI
</Tag>
<Tag colorful gradient type="ghost">
<template #prefixIcon>
<IconAIFilledLevel3 size="small" />
</template>
AI
</Tag>
<Tag colorful type="solid">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
<Tag colorful type="light">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
<Tag colorful type="ghost">
<template #prefixIcon>
<IconAIFilledLevel1 size="small" />
</template>
AI
</Tag>
</div>
</div>
</template>Type
Tag supports three different types, including: light(default), ghost, solid.
Code
<script setup lang="ts">
import { IconGithubLogo, IconSemiLogo } from '@fibrous/semi-icons-vue';
import { Space, Tag, type TagType } from '@fibrous/semi-ui-vue';
const types: [TagType, string][] = [
['light', 'Light'],
['ghost', 'Ghost'],
['solid', 'Solid'],
];
</script>
<template>
<Space wrap>
<template v-for="[type, label] in types" :key="type">
<Tag color="light-blue" shape="circle" size="large" :type="type">
<template #prefixIcon>
<IconGithubLogo />
</template>
Semi Design {{ label }} Tag
</Tag>
<Tag color="cyan" shape="circle" size="large" :type="type">
D2C: figma to code in one click
<template #suffixIcon>
<IconSemiLogo />
</template>
</Tag>
</template>
</Space>
</template>Avatar Tag
You can get a avatar tag with avatarSrc property. avatarShape can change the shape of avatar tag including square(default) and circle.
Code
<script setup lang="ts">
import { Space, Tag } from '@fibrous/semi-ui-vue';
const src = '/assets/placeholder/avatar-a.svg';
</script>
<template>
<Space align="start" vertical>
<Tag :avatarSrc="src">焦锐志</Tag>
<Tag :avatarSrc="src" size="large">焦锐志</Tag>
<Tag :avatarSrc="src" closable size="large">焦锐志</Tag>
<Tag :avatarSrc="src" avatarShape="circle">焦锐志</Tag>
<Tag :avatarSrc="src" avatarShape="circle" size="large">焦锐志</Tag>
<Tag :avatarSrc="src" avatarShape="circle" closable size="large">焦锐志</Tag>
</Space>
</template>Invisible
You can use visible property to control whether the tag is visible.
Code
<script setup lang="ts">
import { ref } from 'vue';
import { Radio, RadioGroup, Tag, type RadioValue } from '@fibrous/semi-ui-vue';
const value = ref<RadioValue | undefined>(0);
</script>
<template>
<div>
<RadioGroup v-model="value" type="button">
<Radio :value="1">Show</Radio>
<Radio :value="0">Hide</Radio>
</RadioGroup>
<div :style="{ marginTop: '10px' }">
<Tag color="light-blue" size="large" :visible="value === 1">Invisible tag</Tag>
</div>
</div>
</template>TagGroup
You can pass in configs for tags through tagList to create a TagGroup. The maxTagCount can be used to cap the number of list and will be displayed as +N when the limit is exceeded.
Set the showPopover property to control whether the remaining content is displayed by Popover when hover to + N Tag
Code
<script setup lang="ts">
import { TagGroup, type TagGroupItem } from '@fibrous/semi-ui-vue';
const src = '/assets/placeholder/avatar-a.svg';
const tagList: TagGroupItem[] = [
{ color: 'light-blue', children: '抖音' },
{ color: 'cyan', children: '火山' },
{ color: 'violet', children: '剪映' },
{ color: 'white', children: '醒图' },
];
const tagList2: TagGroupItem[] = [
{ color: 'white', children: 'Douyin', avatarSrc: src },
{ color: 'white', children: 'Hotsoon', avatarSrc: src },
{ color: 'white', children: 'Capcut', avatarSrc: src },
{ color: 'white', children: 'Xingtu', avatarSrc: src },
];
const divStyle = {
backgroundColor: 'var(--semi-color-fill-0)',
height: '35px',
width: '300px',
display: 'flex',
alignItems: 'center',
padding: '0 10px',
marginBottom: '30px',
};
const tagGroupStyle = {
display: 'flex',
alignItems: 'center',
width: '350px',
};
</script>
<template>
<div :style="divStyle">
<TagGroup :maxTagCount="3" size="large" :style="tagGroupStyle" :tagList="tagList" />
</div>
<div :style="divStyle">
<TagGroup avatarShape="circle" :maxTagCount="2" showPopover size="large" :style="tagGroupStyle" :tagList="tagList2" />
</div>
</template>If the tags in the TagGroup can be deleted, the user needs to process the tagList passed to the TagGroup in the @tagClose handler. Provide a tagKey for every item when tags are removed from the list; otherwise removing the earlier of two tags with the same text shifts the later one onto its instance. Items of tagList take string | number as children; use the #tag="{ tag, index }" slot to render a fully custom node for each tag.
Code
<script setup lang="ts">
import { ref } from 'vue';
import { TagGroup, type TagCloseEvent, type TagGroupItem } from '@fibrous/semi-ui-vue';
const tagList = ref<TagGroupItem[]>([
{ tagKey: '1', color: 'light-blue', children: '抖音', closable: true },
{ tagKey: '3', color: 'cyan', children: '剪映', closable: true },
{ tagKey: '2', color: 'violet', children: '醒图', closable: true },
{ tagKey: '4', color: 'teal', children: '轻颜相机', closable: true },
{ tagKey: '5', color: 'white', children: '飞书', closable: true },
]);
const closeTag = (_event: TagCloseEvent, tagKey: string | number | undefined) => {
tagList.value = tagList.value.filter((tag) => tag.tagKey !== tagKey);
};
</script>
<template>
<div
:style="{
backgroundColor: 'var(--semi-color-fill-0)',
height: '35px',
width: '300px',
display: 'flex',
alignItems: 'center',
padding: '0 10px',
marginBottom: '30px',
}"
>
<TagGroup :maxTagCount="3" showPopover size="large" :style="{ display: 'flex', alignItems: 'center', width: '350px' }" :tagList="tagList" @tagClose="closeTag" />
</div>
</template>SplitTagGroup
Use SplitTagGroup to combine multiple tags into a single connected group. The first and last tags keep their rounded corners while the middle tags are rendered with a square edge, producing a continuous visual unit.
Code
<script setup lang="ts">
import { Space, SplitTagGroup, Tag } from '@fibrous/semi-ui-vue';
</script>
<template>
<Space align="start" vertical>
<SplitTagGroup>
<Tag color="blue" type="solid">标签一</Tag>
<Tag color="cyan" type="solid">标签二</Tag>
<Tag color="teal" type="solid">标签三</Tag>
</SplitTagGroup>
<SplitTagGroup>
<Tag color="violet" shape="circle">组合</Tag>
<Tag color="purple" shape="circle">标签</Tag>
<Tag color="pink" shape="circle">示例</Tag>
<Tag color="red" shape="circle">效果</Tag>
</SplitTagGroup>
<SplitTagGroup>
<Tag color="amber" type="light">浅色</Tag>
<Tag color="orange" type="light">组合</Tag>
<Tag color="yellow" type="light">标签</Tag>
</SplitTagGroup>
<SplitTagGroup>
<Tag color="green" type="ghost">镂空</Tag>
<Tag color="light-green" type="ghost">样式</Tag>
<Tag color="lime" type="ghost">组合</Tag>
</SplitTagGroup>
</Space>
</template>API Reference
Tag
Props
| Property | Description | Type | Default |
|---|---|---|---|
| tabindex | tabindex of the tag. An interactive tag defaults to 0. | number | semiGlobalDefault("Tag", "tabindex") |
| tagKey | Unique identifier of the tag, passed as the second argument of close. | string | number | semiGlobalDefault("Tag", "tagKey") |
| size | Tag size: small, default or large. | "default" | "small" | "large" | semiDefault("Tag", "size", "default") |
| color | Tag color: one of the 16 palette colors or white. | Type"grey" | "red" | "pink" | "purple" | "violet" | "indigo" | "blue" | "light-blue" | "cyan" | "teal" | "green" | "light-green" | "lime" | "yellow" | "amber" | "orange" | "white" | semiDefault("Tag", "color", "grey") |
| type | Style type: light, ghost or solid. | "light" | "solid" | "ghost" | semiDefault("Tag", "type", "light") |
| closable | Whether the tag can be closed. | boolean | semiDefault("Tag", "closable", false) |
| visible | Whether the tag is visible, used with v-model:visible. When given, this value decides. | boolean | semiGlobalDefault("Tag", "visible") |
| avatarSrc | Avatar image URL. Setting it makes an avatar tag. | string | semiGlobalDefault("Tag", "avatarSrc") |
| colorful | Whether the tag is colorful. | boolean | semiDefault("Tag", "colorful", false) |
| gradient | Whether a colorful tag uses a gradient. Requires colorful. | boolean | semiDefault("Tag", "gradient", false) |
| avatarShape | Shape of the avatar in an avatar tag: square or circle. | AvatarShape | semiDefault("Tag", "avatarShape", "square") |
| shape | Tag shape: square or circle. | TagShape | semiDefault("Tag", "shape", "square") |
Events
| Event | Description | Callback parameters |
|---|---|---|
| close | Emitted when the tag is closed: a click event for the close icon, a keydown event for Backspace or Delete. Call preventDefault on the event to keep the tag visible. | [event: TagCloseEvent, tagKey: string | number | undefined] |
| update:visible | Emitted when closing the tag changes its visibility, for v-model:visible to write back. | [visible: boolean] |
| keydown | Emitted when a key is pressed on the tag. | [event: KeyboardEvent] |
Slots
| Slot | Description | Scope parameters |
|---|---|---|
| default | Tag content. | any |
| prefixIcon | Icon before the content. | any |
| suffixIcon | Icon after the content. | any |
Exposes
| Name | Description | Type |
|---|---|---|
| None |
class, style and native attributes passed as attrs land on the root element. A @click listener makes the tag interactive.
TagGroup
Props
| Property | Description | Type | Default |
|---|---|---|---|
| tagList | Tag configurations. Each item holds the props of a Tag, with children as the string or number label. | TagGroupItem[] | undefined |
| maxTagCount | Maximum number of visible tags. The rest is shown as +N. | number | semiGlobalDefault("TagGroup", "maxTagCount") |
| restCount | The number shown in +N. Defaults to the number of tags beyond maxTagCount. | number | semiGlobalDefault("TagGroup", "restCount") |
| size | Size of the tags in the group. | "default" | "small" | "large" | semiDefault("TagGroup", "size", "default") |
| showPopover | Whether hovering +N shows the remaining tags in a Popover. | boolean | semiGlobalDefault("TagGroup", "showPopover") |
| popoverProps | Props passed to the Popover, such as position and trigger. | PopoverProps | semiGlobalDefault("TagGroup", "popoverProps") |
| avatarShape | Avatar shape of the avatar tags in the group. | AvatarShape | semiDefault("TagGroup", "avatarShape", "square") |
Events
| Event | Description | Callback parameters |
|---|---|---|
| tagClose | Emitted when a tag in the group is closed, with the close event and the tagKey of the tag. Update tagList in the handler. | [event: TagCloseEvent, tagKey: string | number | undefined] |
| plusNMouseEnter | Emitted when the pointer enters the +N tag. | [] |
Slots
| Slot | Description | Scope parameters |
|---|---|---|
| tag | Custom rendering of each tag, receiving the tag configuration tag and its index. | { tag: TagGroupItem; index: number; } |
Exposes
| Name | Description | Type |
|---|---|---|
| None |
class, style and native attributes passed as attrs land on the root element of the TagGroup.
SplitTagGroup
Props
| Property | Description | Type | Default |
|---|---|---|---|
| None |
Events
| Event | Description | Callback parameters |
|---|---|---|
| None |
Slots
| Slot | Description | Scope parameters |
|---|---|---|
| default | The Tag components combined into one. | any |
Exposes
| Name | Description | Type |
|---|---|---|
| None |
class, style, aria-label and other native attributes passed as attrs land on the root element.
Accessibility
ARIA
aria-labelis used to indicate the role ofTag, for deletable or clickableTag, we recommend using this attribute
Keyboard and Focus
- If the current
Tagis interactive, then thisTagcan be focused. Such as:- When the
onClickattribute (@clickin Vue) is used, the keyboard user can activate thisTagwith theEnterorSpacekey - When the
closableproperty istrue, keyboard users can delete thisTagby pressing theDeleteorBackspacekey, and focus moves to the adjacent focusableTag
- When the
Content Guidelines
- Due to limited space, label text should be as short as possible
- avoid line breaks
- use sentence case
Design Tokens
| Sass variable | Value | Usage |
|---|---|---|
| $color-tag_avatar-bg-default | var(--semi-color-bg-4) | 头像标签背景颜色 - 默认 |
| $color-tag_avatar-border-default | var(--semi-color-border) | 头像标签描边颜色 - 默认 |
| $color-tag_avatar-text-default | var(--semi-color-text-0) | 头像标签文字颜色 - 默认 |
| $color-tag_white-bg-default | var(--semi-color-bg-4) | 白色标签背景颜色 - 默认 |
| $color-tag_white-border-default | rgb(from var(--semi-grey-2) r g b / 0.7) | 白色标签描边颜色 - 默认 |
| $color-tag_white-text-default | var(--semi-color-text-0) | 白色标签文字颜色 - 默认 |
| $color-tag_white-icon-default | var(--semi-color-text-2) | 白色标签图标颜色 - 默认 |
| $color-tag-outline-focus | $color-focus-ring | 标签轮廓 - 聚焦 |
| $color-tag_colorful_solid-bg | var(--semi-color-ai-purple) | AI Tag深色底色类型背景色 |
| $color-tag_colorful_solid-text | var(--semi-color-white) | AI Tag 深色底色类型字体颜色 |
| $color-tag_colorful_solid_gradient-bg | var(--semi-color-ai-general) | AI Tag深色底色类型渐变背景色 |
| $color-tag_colorful_light-bg | var(--semi-ai-purple-0) | AI Tag 浅色底色类型背景色 |
| $color-tag_colorful_light-text | var(--semi-color-ai-purple) | AI Tag 浅色底色类型字体颜色 |
| $color-tag_colorful_light_gradient-bg | var(--semi-ai-general-0) | AI Tag浅色底色类型背景色-渐变 |
| $color-tag_colorful_light_gradient-text | var(--semi-color-ai-general) | AI Tag浅色底色类型字体色-渐变 |
| $color-tag_colorful_light_gradient-1 | var(--semi-ai-general-5-0) | AI Tag 浅色底色icon渐变色1 |
| $color-tag_colorful_light_gradient-2 | var(--semi-ai-general-5-1) | AI Tag 浅色底色icon渐变色2 |
| $color-tag_colorful_light_gradient-3 | var(--semi-ai-general-5-2) | AI Tag 浅色底色icon渐变色3 |
| $color-tag_colorful_light_gradient-4 | var(--semi-ai-general-5-3) | AI Tag 浅色底色icon渐变色4 |
| $color-tag_colorful_ghost-bg | var(--semi-color-white) | AI Tag 白色底色类型背景色 |
| $color-tag_colorful_ghost-text | var(--semi-color-ai-purple) | AI Tag 白色底色类型字体颜色 |
| $color-tag_colorful_ghost-border | var(--semi-color-ai-general) | AI Tag 白色底色类型描边颜色 |
| $color-tag_colorful_ghost_gradient-text | var(--semi-color-ai-general) | AI Tag 白色底色类型字体色-渐变 |
| $color-tag_colorful_ghost_gradient-1 | var(--semi-ai-general-5-0) | AI Tag 白色底色icon渐变色1 |
| $color-tag_colorful_ghost_gradient-2 | var(--semi-ai-general-5-1) | AI Tag 白色底色icon渐变色2 |
| $color-tag_colorful_ghost_gradient-3 | var(--semi-ai-general-5-2) | AI Tag 白色底色icon渐变色3 |
| $color-tag_colorful_ghost_gradient-4 | var(--semi-ai-general-5-3) | AI Tag 白色底色icon渐变色4 |
| $width-tag_avatar_circle_small | 16px | 头像标签圆角 - 小尺寸 |
| $width-tag_avatar_circle_large | 20px | 头像标签圆角 - 大尺寸 |
| $width-tag-border | 1px | 标签描边宽度 |
| $width-tag_avatar-border | $width-tag-border | 头像标签描边宽度 |
| $width-tag-outline | $width-focus-ring | 标签轮廓宽度 |
| $height-tag_small | 20px | 小尺寸标签高度 |
| $height-tag_large | 24px | 大尺寸标签高度 |
| $radius-tag | var(--semi-border-radius-small) | 标签圆角大小 |
| $radius-tag_circle | var(--semi-border-radius-full) | 胶囊标签圆角大小 |
| $spacing-tag_small-paddingY | 2px | 小尺寸标签垂直方向内边距 |
| $spacing-tag_small-paddingX | $spacing-tight | 小尺寸标签水平方向内边距 |
| $spacing-tag_prefix_icon_paddingRight | $spacing-extra-tight | 后缀图标右侧边距 |
| $spacing-tag_suffix_icon_paddingLeft | $spacing-extra-tight | 后缀图标左侧边距 |
| $spacing-tag_large-paddingY | 4px | 大尺寸标签垂直方向内边距 |
| $spacing-tag_large-paddingX | $spacing-tight | 大尺寸标签水平方向内边距 |
| $color-tag_close-icon-default | var(--semi-color-text-2) | 可删除的标签删除按钮颜色 |
| $color-tag_close-icon-hover | var(--semi-color-text-1) | 可删除的标签删除按钮颜色 - 悬浮 |
| $color-tag_close-icon-active | var(--semi-color-text-0) | 可删除的标签删除按钮颜色 - 按下 |
| $spacing-tag_close-paddingLeft | $spacing-extra-tight | 可删除的标签删除按钮左侧内边距 |
| $spacing-tag_closable-paddingTop | $spacing-extra-tight | 可删除的标签删除按钮顶部内边距 |
| $spacing-tag_closable-paddingRight | $spacing-extra-tight | 可删除的标签删除按钮右侧内边距 |
| $spacing-tag_closable-paddingBottom | $spacing-extra-tight | 可删除的标签删除按钮底部内边距 |
| $spacing-tag_closable-paddingLeft | $spacing-tight | 可删除的标签删除按钮左侧内边距 |
| $spacing-tag_avatar-marginRight | $spacing-extra-tight | 头像标签头像右侧外边距 |
| $spacing-tag_avatar_square-paddingTop | 0 | 方形头像标签头像顶部内边距 |
| $spacing-tag_avatar_square-paddingRight | $spacing-extra-tight | 方形头像标签头像右侧内边距 |
| $spacing-tag_avatar_square-paddingBottom | 0 | 方形头像标签头像底部内边距 |
| $spacing-tag_avatar_square-paddingLeft | 0 | 方形头像标签头像左侧内边距 |
| $spacing-tag_avatar_circle-paddingTop | $spacing-super-tight | 圆型头像标签头像顶部内边距 |
| $spacing-tag_avatar_circle-paddingRight | $spacing-extra-tight | 圆型头像标签头像右侧内边距 |
| $spacing-tag_avatar_circle-paddingBottom | $spacing-super-tight | 圆型头像标签头像底部内边距 |
| $spacing-tag_avatar_circle-paddingLeft | $spacing-super-tight | 圆型头像标签头像左侧内边距 |
| $color-tag_avatar_square_img-bg-default | var(--semi-color-default) | 方形头像标签头像背景色 - 默认 |
| $spacing-tag_group-marginBottom | 0 | 标签组底部外边距 |
| $spacing-tag_group-marginRight | $spacing-tight | 标签组右侧外边距 |
| $font-tag_colorful-fontWeight | $font-weight-bold | AI tag的字重 |