Show · Tag

Tag

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

Demos

How to import

<script lang="ts">
    import { Tag, TagGroup, SplitTagGroup } from '@fibrae/semi-ui-svelte';
</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 call onClose(event, tagKey), and calling preventDefault on the event in onClose keeps the tag shown after clicking. The tag content goes inside the Tag tag, as the children snippet.

default tag
Closable Tag
Closable Tag, Prevent Default
Code
<script lang="ts">
    import { Space, Tag, type TagCloseEvent } from '@fibrae/semi-ui-svelte';

    const preventClose = (event: TagCloseEvent) => event.preventDefault();
</script>

<div>
    <Space>
        <Tag>default tag</Tag>
        <Tag closable>Closable Tag</Tag>
        <Tag closable onClose={preventClose}>Closable Tag, Prevent Default</Tag>
    </Space>
</div>

Size

Supports two sizes: large and small (default).

small tag
large tag
Code
<script lang="ts">
    import { Space, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space>
    <Tag color="light-blue" size="small">small tag</Tag>
    <Tag color="cyan" size="large">large tag</Tag>
</Space>

Shape

Supports two Shape: square(default)、circle。

small circle tag
large circle tag
Code
<script lang="ts">
    import { Space, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space>
    <Tag color="amber" shape="circle" size="small">small circle tag</Tag>
    <Tag color="violet" shape="circle" size="large">large circle tag</Tag>
</Space>

Icon

Use the prefixIcon and suffixIcon snippets to add icons before or after the content: write {#snippet prefixIcon()}...{/snippet} inside the Tag tag, or define it and pass it as a prop.

Semi Design
D2C: figma to code in one click
Code
<script lang="ts">
    import { IconGithubLogo, IconSemiLogo } from '@fibrae/semi-icons-svelte';
    import { Space, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space>
    <Tag color="light-blue" shape="circle" size="large">
        {#snippet prefixIcon()}
            <IconGithubLogo />
        {/snippet}
        Semi Design
    </Tag>
    <Tag color="cyan" shape="circle" size="large">
        D2C: figma to code in one click
        {#snippet suffixIcon()}
            <IconSemiLogo />
        {/snippet}
    </Tag>
</Space>

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 lang="ts">
    import { Space, Tag, type TagColor } from '@fibrae/semi-ui-svelte';

    const colors: TagColor[] = ['amber', 'blue', 'cyan', 'green', 'grey', 'indigo', 'light-blue', 'light-green', 'lime', 'orange', 'pink', 'purple', 'red', 'teal', 'violet', 'yellow', 'white'];
</script>

<Space wrap>
    {#each colors as color (color)}
        <Tag {color}>{color}</Tag>
    {/each}
</Space>

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 lang="ts">
    import { IconAIFilledLevel1, IconAIFilledLevel3 } from '@fibrae/semi-icons-svelte';
    import { Tag } from '@fibrae/semi-ui-svelte';

    const grid = 'display: grid; grid-template-columns: repeat(3, 1fr); grid-gap: 10px; width: fit-content';
</script>

{#snippet level1()}
    <IconAIFilledLevel1 size="small" />
{/snippet}
{#snippet level3()}
    <IconAIFilledLevel3 size="small" />
{/snippet}

<div style="display: flex; flex-direction: column; row-gap: 30px">
    <div style={grid}>
        <Tag colorful gradient prefixIcon={level1} shape="circle" type="solid">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} shape="circle" type="light">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} shape="circle" type="ghost">AI</Tag>
        <Tag colorful prefixIcon={level1} shape="circle" type="solid">AI</Tag>
        <Tag colorful prefixIcon={level1} shape="circle" type="light">AI</Tag>
        <Tag colorful prefixIcon={level1} shape="circle" type="ghost">AI</Tag>
    </div>
    <div style={grid}>
        <Tag colorful gradient prefixIcon={level1} type="solid">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} type="light">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} type="ghost">AI</Tag>
        <Tag colorful prefixIcon={level1} type="solid">AI</Tag>
        <Tag colorful prefixIcon={level1} type="light">AI</Tag>
        <Tag colorful prefixIcon={level1} type="ghost">AI</Tag>
    </div>
</div>

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 lang="ts">
    import { IconGithubLogo, IconSemiLogo } from '@fibrae/semi-icons-svelte';
    import { Space, Tag, type TagType } from '@fibrae/semi-ui-svelte';

    const types: [TagType, string][] = [
        ['light', 'Light'],
        ['ghost', 'Ghost'],
        ['solid', 'Solid'],
    ];
</script>

<Space wrap>
    {#each types as [type, label] (type)}
        <Tag color="light-blue" shape="circle" size="large" {type}>
            {#snippet prefixIcon()}
                <IconGithubLogo />
            {/snippet}
            Semi Design {label} Tag
        </Tag>
        <Tag color="cyan" shape="circle" size="large" {type}>
            D2C: figma to code in one click
            {#snippet suffixIcon()}
                <IconSemiLogo />
            {/snippet}
        </Tag>
    {/each}
</Space>

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 lang="ts">
    import { Space, Tag } from '@fibrae/semi-ui-svelte';

    const src = '/assets/placeholder/avatar-a.svg';
</script>

<Space align="start" vertical>
    <Tag avatarSrc={src}>焦锐志</Tag>
    <Tag avatarSrc={src} size="large">焦锐志</Tag>
    <Tag avatarSrc={src} closable size="large">焦锐志</Tag>
    <Tag avatarShape="circle" avatarSrc={src}>焦锐志</Tag>
    <Tag avatarShape="circle" avatarSrc={src} size="large">焦锐志</Tag>
    <Tag avatarShape="circle" avatarSrc={src} closable size="large">焦锐志</Tag>
</Space>

Invisible

You can use visible property to control whether the tag is visible.

Invisible tag
Code
<script lang="ts">
    import { Radio, RadioGroup, Tag, type RadioValue } from '@fibrae/semi-ui-svelte';

    let value = $state<RadioValue | undefined>(0);
</script>

<div>
    <RadioGroup aria-label="标签可见性" bind:value name="demo-tag-visible" type="button">
        <Radio value={1}>Show</Radio>
        <Radio value={0}>Hide</Radio>
    </RadioGroup>
    <div style="margin-top: 10px">
        <Tag color="light-blue" size="large" visible={value === 1}>Invisible tag</Tag>
    </div>
</div>

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 lang="ts">
    import { TagGroup, type TagGroupItem } from '@fibrae/semi-ui-svelte';

    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 = 'background-color: var(--semi-color-fill-0); height: 35px; width: 300px; display: flex; align-items: center; padding: 0 10px; margin-bottom: 30px';
    const tagGroupStyle = 'display: flex; align-items: center; width: 350px';
</script>

<div style={divStyle}>
    <TagGroup maxTagCount={3} size="large" style={tagGroupStyle} {tagList} />
</div>
<div style={divStyle}>
    <TagGroup avatarShape="circle" maxTagCount={2} showPopover size="large" style={tagGroupStyle} tagList={tagList2} />
</div>

If the tags in the TagGroup can be deleted, the user needs to update the tagList passed to the TagGroup in onTagClose. 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 snippet, whose parameter is { tag, index }, to render a fully custom node for each tag. Both the item's own onClose in tagList and the group's onTagClose are called.

抖音
剪映
醒图
+2
Code
<script lang="ts">
    import { TagGroup, type TagCloseEvent, type TagGroupItem } from '@fibrae/semi-ui-svelte';

    let tagList = $state<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 = tagList.filter((tag) => tag.tagKey !== tagKey);
    };
</script>

<div style="background-color: var(--semi-color-fill-0); height: 35px; width: 300px; display: flex; align-items: center; padding: 0 10px; margin-bottom: 30px">
    <TagGroup maxTagCount={3} onTagClose={closeTag} showPopover size="large" style="display: flex; align-items: center; width: 350px" {tagList} />
</div>

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 lang="ts">
    import { Space, SplitTagGroup, Tag } from '@fibrae/semi-ui-svelte';
</script>

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

API Reference

Tag

Props

PropertyDescriptionTypeDefault
avatarShapeShape of the avatar in an avatar tag: square or circle.AvatarShape"square"
avatarSrcAvatar image URL. Setting it makes an avatar tag.string-
childrenSnippet for the tag content.Snippet-
closableWhether the tag can be closed.booleanfalse
colorTag color: one of the 16 palette colors or white.TagColor"grey"
colorfulWhether the tag is colorful.booleanfalse
gradientWhether a colorful tag uses a gradient. Requires colorful.booleanfalse
onCloseCalled when the tag is closed, with the close event and the tagKey: a click event for the close icon, a keydown event for Backspace or Delete. Call preventDefault on the event to keep the tag visible.Type(event: TagCloseEvent, tagKey?: string | number) => void-
onkeydownCalled when a key is pressed on the tag.TypeKeyboardEventHandler<T> | null-
prefixIconSnippet for the icon before the content.Snippet-
shapeTag shape: square or circle.TagShape"square"
sizeTag size: small, default or large.TagSize"default"
suffixIconSnippet for the icon after the content.Snippet-
tabindextabindex of the tag. An interactive tag defaults to 0.number | null-
tagKeyUnique identifier of the tag, passed as the second argument of onClose.string | number-
typeStyle type: light, ghost or solid.TagType"light"
visibleWhether the tag is visible; bind it with bind:visible. The setter of a function binding can reject closing. Without it the tag closes itself and shows until then.boolean-

class, style and native attributes are spread onto the root element (div); native events use lowercase names (onclick, onmouseenter). An onclick listener or closable makes the tag interactive.

TagGroup

Props

PropertyDescriptionTypeDefault
avatarShapeAvatar shape of the avatar tags in the group.AvatarShape"square"
maxTagCountMaximum number of visible tags. The rest is shown as +N.number-
onPlusNMouseEnterCalled when the pointer enters the +N tag.Type(event: MouseEvent) => void-
onTagCloseCalled when a tag in the group is closed, with the close event and the tagKey of the tag; the item's own onClose is called too. Update tagList in the callback.Type(event: TagCloseEvent, tagKey?: string | number) => void-
popoverPropsProps passed to the Popover, such as position and trigger; child and content are fixed by TagGroup.PopoverProps-
restCountThe number shown in +N. Defaults to the number of tags beyond maxTagCount.number-
showPopoverWhether hovering +N shows the remaining tags in a Popover.boolean-
sizeSize of the tags in the group.TagSize"default"
tagSnippet for custom rendering of each tag, with the parameter { tag, index }: the tag configuration and its index, counted across the visible tags and the +N popover.TypeSnippet<[scope: { tag: TagGroupItem; index: number }]>-
tagListTag configurations. Each item holds the props of a Tag, with children as the string or number label.TagGroupItem[]-

class, style and native attributes are spread onto the TagGroup root element (div). The +N Tag is itself the Popover trigger, with no extra span around it.

SplitTagGroup

Props

PropertyDescriptionTypeDefault
childrenSnippet for the Tag components combined into one.Snippet-

class, style, aria-label and other native attributes are spread onto the root element (div). The root role is fixed to group.

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, onclick in Svelte) 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的字重