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.
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).
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。
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.
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.
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.
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.
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.
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
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.
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
| Property | Description | Type | Default |
|---|---|---|---|
| avatarShape | Shape of the avatar in an avatar tag: square or circle. | AvatarShape | "square" |
| avatarSrc | Avatar image URL. Setting it makes an avatar tag. | string | - |
| children | Snippet for the tag content. | Snippet | - |
| closable | Whether the tag can be closed. | boolean | false |
| color | Tag color: one of the 16 palette colors or white. | TagColor | "grey" |
| colorful | Whether the tag is colorful. | boolean | false |
| gradient | Whether a colorful tag uses a gradient. Requires colorful. | boolean | false |
| onClose | Called 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 | - |
| onkeydown | Called when a key is pressed on the tag. | TypeKeyboardEventHandler<T> | null | - |
| prefixIcon | Snippet for the icon before the content. | Snippet | - |
| shape | Tag shape: square or circle. | TagShape | "square" |
| size | Tag size: small, default or large. | TagSize | "default" |
| suffixIcon | Snippet for the icon after the content. | Snippet | - |
| tabindex | tabindex of the tag. An interactive tag defaults to 0. | number | null | - |
| tagKey | Unique identifier of the tag, passed as the second argument of onClose. | string | number | - |
| type | Style type: light, ghost or solid. | TagType | "light" |
| visible | Whether 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
| Property | Description | Type | Default |
|---|---|---|---|
| avatarShape | Avatar shape of the avatar tags in the group. | AvatarShape | "square" |
| maxTagCount | Maximum number of visible tags. The rest is shown as +N. | number | - |
| onPlusNMouseEnter | Called when the pointer enters the +N tag. | Type(event: MouseEvent) => void | - |
| onTagClose | Called 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 | - |
| popoverProps | Props passed to the Popover, such as position and trigger; child and content are fixed by TagGroup. | PopoverProps | - |
| restCount | The number shown in +N. Defaults to the number of tags beyond maxTagCount. | number | - |
| showPopover | Whether hovering +N shows the remaining tags in a Popover. | boolean | - |
| size | Size of the tags in the group. | TagSize | "default" |
| tag | Snippet 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 }]> | - |
| tagList | Tag 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
| Property | Description | Type | Default |
|---|---|---|---|
| children | Snippet 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-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,onclickin Svelte) 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的字重 |