Show · Tag

Tag

Tag component is used to display a collection of concise information for rapid identification and grouping.

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

default tag
Closable Tag
Closable Tag, Prevent Default
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).

small tag
large tag
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。

small circle tag
large circle tag
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.

Semi Design
D2C: figma to code in one click
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.

amber
blue
cyan
green
grey
indigo
light-blue
light-green
lime
orange
pink
purple
red
teal
violet
yellow
white
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.

AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
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.

Semi Design Light Tag
D2C: figma to code in one click
Semi Design Ghost Tag
D2C: figma to code in one click
Semi Design Solid Tag
D2C: figma to code in one click
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.

Invisible tag
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

抖音
火山
剪映
+1
Douyin
Hotsoon
+2
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.

抖音
剪映
醒图
+2
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

PropertyDescriptionTypeDefault
tabindextabindex of the tag. An interactive tag defaults to 0.numbersemiGlobalDefault("Tag", "tabindex")
tagKeyUnique identifier of the tag, passed as the second argument of close.string | numbersemiGlobalDefault("Tag", "tagKey")
sizeTag size: small, default or large."default" | "small" | "large"semiDefault("Tag", "size", "default")
colorTag 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")
typeStyle type: light, ghost or solid."light" | "solid" | "ghost"semiDefault("Tag", "type", "light")
closableWhether the tag can be closed.booleansemiDefault("Tag", "closable", false)
visibleWhether the tag is visible, used with v-model:visible. When given, this value decides.booleansemiGlobalDefault("Tag", "visible")
avatarSrcAvatar image URL. Setting it makes an avatar tag.stringsemiGlobalDefault("Tag", "avatarSrc")
colorfulWhether the tag is colorful.booleansemiDefault("Tag", "colorful", false)
gradientWhether a colorful tag uses a gradient. Requires colorful.booleansemiDefault("Tag", "gradient", false)
avatarShapeShape of the avatar in an avatar tag: square or circle.AvatarShapesemiDefault("Tag", "avatarShape", "square")
shapeTag shape: square or circle.TagShapesemiDefault("Tag", "shape", "square")

Events

EventDescriptionCallback parameters
closeEmitted 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:visibleEmitted when closing the tag changes its visibility, for v-model:visible to write back.[visible: boolean]
keydownEmitted when a key is pressed on the tag.[event: KeyboardEvent]

Slots

SlotDescriptionScope parameters
defaultTag content.any
prefixIconIcon before the content.any
suffixIconIcon after the content.any

Exposes

NameDescriptionType
None

class, style and native attributes passed as attrs land on the root element. A @click listener makes the tag interactive.

TagGroup

Props

PropertyDescriptionTypeDefault
tagListTag configurations. Each item holds the props of a Tag, with children as the string or number label.TagGroupItem[]undefined
maxTagCountMaximum number of visible tags. The rest is shown as +N.numbersemiGlobalDefault("TagGroup", "maxTagCount")
restCountThe number shown in +N. Defaults to the number of tags beyond maxTagCount.numbersemiGlobalDefault("TagGroup", "restCount")
sizeSize of the tags in the group."default" | "small" | "large"semiDefault("TagGroup", "size", "default")
showPopoverWhether hovering +N shows the remaining tags in a Popover.booleansemiGlobalDefault("TagGroup", "showPopover")
popoverPropsProps passed to the Popover, such as position and trigger.PopoverPropssemiGlobalDefault("TagGroup", "popoverProps")
avatarShapeAvatar shape of the avatar tags in the group.AvatarShapesemiDefault("TagGroup", "avatarShape", "square")

Events

EventDescriptionCallback parameters
tagCloseEmitted 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]
plusNMouseEnterEmitted when the pointer enters the +N tag.[]

Slots

SlotDescriptionScope parameters
tagCustom rendering of each tag, receiving the tag configuration tag and its index.{ tag: TagGroupItem; index: number; }

Exposes

NameDescriptionType
None

class, style and native attributes passed as attrs land on the root element of the TagGroup.

SplitTagGroup

Props

PropertyDescriptionTypeDefault
None

Events

EventDescriptionCallback parameters
None

Slots

SlotDescriptionScope parameters
defaultThe Tag components combined into one.any

Exposes

NameDescriptionType
None

class, style, aria-label and other native attributes passed as attrs land on the root element.

Accessibility

ARIA

  • aria-label is used to indicate the role of Tag, for deletable or clickable Tag, we recommend using this attribute

Keyboard and Focus

  • If the current Tag is interactive, then this Tag can be focused. Such as:
    • When the onClick attribute (@click in Vue) is used, the keyboard user can activate this Tag with the Enter or Space key
    • When the closable property is true, keyboard users can delete this Tag by pressing the Delete or Backspace key, and focus moves to the adjacent focusable Tag

Content Guidelines

  • Due to limited space, label text should be as short as possible
  • avoid line breaks
  • use sentence case

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.
Sass variableValueUsage
$color-tag_avatar-bg-defaultvar(--semi-color-bg-4)头像标签背景颜色 - 默认
$color-tag_avatar-border-defaultvar(--semi-color-border)头像标签描边颜色 - 默认
$color-tag_avatar-text-defaultvar(--semi-color-text-0)头像标签文字颜色 - 默认
$color-tag_white-bg-defaultvar(--semi-color-bg-4)白色标签背景颜色 - 默认
$color-tag_white-border-defaultrgb(from var(--semi-grey-2) r g b / 0.7)白色标签描边颜色 - 默认
$color-tag_white-text-defaultvar(--semi-color-text-0)白色标签文字颜色 - 默认
$color-tag_white-icon-defaultvar(--semi-color-text-2)白色标签图标颜色 - 默认
$color-tag-outline-focus$color-focus-ring标签轮廓 - 聚焦
$color-tag_colorful_solid-bgvar(--semi-color-ai-purple)AI Tag深色底色类型背景色
$color-tag_colorful_solid-textvar(--semi-color-white)AI Tag 深色底色类型字体颜色
$color-tag_colorful_solid_gradient-bgvar(--semi-color-ai-general)AI Tag深色底色类型渐变背景色
$color-tag_colorful_light-bgvar(--semi-ai-purple-0)AI Tag 浅色底色类型背景色
$color-tag_colorful_light-textvar(--semi-color-ai-purple)AI Tag 浅色底色类型字体颜色
$color-tag_colorful_light_gradient-bgvar(--semi-ai-general-0)AI Tag浅色底色类型背景色-渐变
$color-tag_colorful_light_gradient-textvar(--semi-color-ai-general)AI Tag浅色底色类型字体色-渐变
$color-tag_colorful_light_gradient-1var(--semi-ai-general-5-0)AI Tag 浅色底色icon渐变色1
$color-tag_colorful_light_gradient-2var(--semi-ai-general-5-1)AI Tag 浅色底色icon渐变色2
$color-tag_colorful_light_gradient-3var(--semi-ai-general-5-2)AI Tag 浅色底色icon渐变色3
$color-tag_colorful_light_gradient-4var(--semi-ai-general-5-3)AI Tag 浅色底色icon渐变色4
$color-tag_colorful_ghost-bgvar(--semi-color-white)AI Tag 白色底色类型背景色
$color-tag_colorful_ghost-textvar(--semi-color-ai-purple)AI Tag 白色底色类型字体颜色
$color-tag_colorful_ghost-bordervar(--semi-color-ai-general)AI Tag 白色底色类型描边颜色
$color-tag_colorful_ghost_gradient-textvar(--semi-color-ai-general)AI Tag 白色底色类型字体色-渐变
$color-tag_colorful_ghost_gradient-1var(--semi-ai-general-5-0)AI Tag 白色底色icon渐变色1
$color-tag_colorful_ghost_gradient-2var(--semi-ai-general-5-1)AI Tag 白色底色icon渐变色2
$color-tag_colorful_ghost_gradient-3var(--semi-ai-general-5-2)AI Tag 白色底色icon渐变色3
$color-tag_colorful_ghost_gradient-4var(--semi-ai-general-5-3)AI Tag 白色底色icon渐变色4
$width-tag_avatar_circle_small16px头像标签圆角 - 小尺寸
$width-tag_avatar_circle_large20px头像标签圆角 - 大尺寸
$width-tag-border1px标签描边宽度
$width-tag_avatar-border$width-tag-border头像标签描边宽度
$width-tag-outline$width-focus-ring标签轮廓宽度
$height-tag_small20px小尺寸标签高度
$height-tag_large24px大尺寸标签高度
$radius-tagvar(--semi-border-radius-small)标签圆角大小
$radius-tag_circlevar(--semi-border-radius-full)胶囊标签圆角大小
$spacing-tag_small-paddingY2px小尺寸标签垂直方向内边距
$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-paddingY4px大尺寸标签垂直方向内边距
$spacing-tag_large-paddingX$spacing-tight大尺寸标签水平方向内边距
$color-tag_close-icon-defaultvar(--semi-color-text-2)可删除的标签删除按钮颜色
$color-tag_close-icon-hovervar(--semi-color-text-1)可删除的标签删除按钮颜色 - 悬浮
$color-tag_close-icon-activevar(--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-paddingTop0方形头像标签头像顶部内边距
$spacing-tag_avatar_square-paddingRight$spacing-extra-tight方形头像标签头像右侧内边距
$spacing-tag_avatar_square-paddingBottom0方形头像标签头像底部内边距
$spacing-tag_avatar_square-paddingLeft0方形头像标签头像左侧内边距
$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-defaultvar(--semi-color-default)方形头像标签头像背景色 - 默认
$spacing-tag_group-marginBottom0标签组底部外边距
$spacing-tag_group-marginRight$spacing-tight标签组右侧外边距
$font-tag_colorful-fontWeight$font-weight-boldAI tag的字重