TagInput

Demos

How to import

<script lang="ts">
    import { Avatar, Button, TagInput, Toast } from '@fibrae/semi-ui-svelte';
</script>

Basic Usage

After pressing the Enter key, the input will add value as a tag. If the tag content is an empty string or pure space, it will be filtered.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山', '西瓜视频']);
</script>

<TagInput bind:value placeholder="请输入..." />

Batch Add

You can use separator to set the separator to achieve batch input, and its default value is a comma. Multiple separators are supported in string[] format.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    const separators = ['-', '/', '|', '++'];
</script>

<TagInput placeholder="使用 - 进行批量输入" separator="-" />
<br />
<br />
<TagInput placeholder="支持多个分隔符进行批量输入" separator={separators} />

Batch Remove

You can also use showClear to set whether to support one-click deletion of all tags and input.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山']);
</script>

<TagInput bind:value placeholder="请输入..." showClear />

Disabled

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山', '西瓜视频']);
</script>

<TagInput bind:value disabled placeholder="请输入..." showClear />

Size

Use size to set the size of the TagInput, optional: small, default, large.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';
</script>

<TagInput placeholder="small" size="small" />
<br />
<br />
<TagInput placeholder="default" />
<br />
<br />
<TagInput placeholder="large" size="large" />

Different validate status

validateStatus: default, warning, error.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';
</script>

<TagInput placeholder="default" />
<br />
<br />
<TagInput placeholder="warning" validateStatus="warning" />
<br />
<br />
<TagInput placeholder="error" validateStatus="error" />

Prefix / Suffix

You can pass the input box prefix through the prefix snippet and the suffix through the suffix snippet, as text or nodes such as icons.
The left and right padding is added automatically when the snippet content is plain text or an Icon. For custom nodes the padding is 0; set it on the nodes you pass in if needed.

<script lang="ts">
    import { IconGift, IconVigoLogo } from '@fibrae/semi-icons-svelte';
    import { TagInput } from '@fibrae/semi-ui-svelte';
</script>

<TagInput>
    {#snippet prefix()}
        <IconVigoLogo />
    {/snippet}
</TagInput>
<br />
<br />
<TagInput>
    {#snippet prefix()}Prefix{/snippet}
</TagInput>
<br />
<br />
<TagInput>
    {#snippet suffix()}
        <IconGift />
    {/snippet}
</TagInput>
<br />
<br />
<TagInput>
    {#snippet suffix()}Suffix{/snippet}
</TagInput>

Autocomplete

You can use addOnBlur to set whether the current input value is automatically created as a tag when the blur event is triggered.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山', '西瓜视频']);
</script>

<TagInput addOnBlur bind:value placeholder="请输入..." />

Allow Duplicates

You can use allowDuplicates to set whether to allow the creation of the same tag.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山', '西瓜视频']);
</script>

<TagInput allowDuplicates={false} bind:value placeholder="请输入..." />

Limits

You can use max to limit the number of tags. Tags added past the limit are dropped, and the onExceed() callback is invoked.

You can use maxLength to limit the maximum length of a single tag, and the onInputExceed() callback will be invoked when this value is exceeded.

<script lang="ts">
    import { TagInput, Toast } from '@fibrae/semi-ui-svelte';
</script>

<TagInput max={3} onExceed={() => Toast.warning('超过 max')} placeholder="最多输入3条标签.." />
<TagInput maxLength={5} onInputExceed={() => Toast.warning('超过 maxLength')} placeholder="单个标签长度不超过5..." style="margin-top: 12px" />

Limit the number of tags displayed

You can use maxTagCount to limit the number of tags displayed, and the excess will be displayed as +N. You can use showRestTagsPopover to set whether hover +N displays Popover after maxTagCount is exceeded, and you can configure Popover in the restTagsPopoverProps property.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山', '西瓜视频']);
    const restTagsPopoverProps = { position: 'top' } as const;
</script>

<TagInput bind:value maxTagCount={2} {restTagsPopoverProps} showRestTagsPopover />

Controlled Tag

Bind the tags with bind:value to control them. There is no defaultValue: a one-way value={x} only seeds the tags, and bind:value={get, set} makes the input fully controlled. Binding value to undefined clears the tags.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音']);
</script>

<TagInput bind:value />

Controlled Input

Bind the input text with bind:inputValue to control it; bind:inputValue={get, set} makes it fully controlled.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let inputValue = $state('abc');
</script>

<TagInput bind:inputValue />

Callback

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音']);
    let logs = $state<string[]>([]);

    const log = (message: string) => {
        logs = [message, ...logs].slice(0, 5);
    };
</script>

<TagInput
    bind:value
    onAdd={(tag) => log(`onAdd，新增：${tag}`)}
    onBlur={() => log('onBlur')}
    onChange={(tags) => log(`onChange，当前标签数组：${tags}`)}
    onFocus={() => log('onFocus')}
    onInputChange={(input) => log(`onInputChange，当前输入内容：${input}`)}
    onRemove={(removed, index) => log(`onRemove，移除：${removed}，序号：${index}`)}
    placeholder="请输入..."
    showClear
/>
<ul>
    {#each logs as message, index (index)}
        <li>{message}</li>
    {/each}
</ul>

Focus Management

Bind the component with bind:this and call its focus() and blur() methods to manage the focus. focus() focuses the input and activates the component; blur() removes the focus from whichever element inside the component holds it.

<script lang="ts">
    import { Button, TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山']);
    let tagInput = $state<ReturnType<typeof TagInput>>();
</script>

<TagInput bind:this={tagInput} bind:value />
<Button style="margin-top: 10px" onclick={() => tagInput?.focus()}>点击按钮聚焦</Button>

Custom TagInput rendering

You can use the tag snippet to replace each tag as a whole; it receives { value, index, onClose }. Empty content renders no tag and does not fall back to the default tag. onClose calls preventDefault on the event it receives, so you can pass it straight to a button's onclick.

夏可漫@semi.com

Code

Copy code

<script lang="ts">
    import { IconClose } from '@fibrae/semi-icons-svelte';
    import { Avatar, Button, TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['夏可漫']);
    const fallbackAvatar = '/assets/placeholder/avatar-a.svg';
    const avatars = new Map([
        ['夏可漫', '/assets/root-web-sites/avatarDemo.jpeg'],
        ['申悦', '/assets/root-web-sites/bf8647bffab13c38772c9ff94bf91a9d.jpg'],
        ['曲晨一', '/assets/root-web-sites/bf8647bffab13c38772c9ff94bf91a9d.jpg'],
        ['文嘉茂', '/assets/root-web-sites/avatarDemo.jpeg'],
    ]);
    const itemStyle = 'background-color: var(--semi-color-info-light-default); padding: 4px 8px; border-radius: 12px; display: flex; align-items: center; font-size: 14px; margin-right: 10px';
</script>

<TagInput bind:value>
    {#snippet tag({ value: tag, onClose })}
        <div style={itemStyle}>
            <Avatar alt="avatar" size="extra-small" src={avatars.get(tag) ?? fallbackAvatar} />
            <span style="margin-left: 8px">{`${tag}@semi.com`}</span>
            <Button aria-label={`移除 ${tag}`} size="small" theme="borderless" type="tertiary" onclick={onClose}>
                {#snippet icon()}
                    <IconClose size="small" />
                {/snippet}
            </Button>
        </div>
    {/snippet}
</TagInput>

Drag to sort

Set draggable to true to enable drag and drop sorting. After the drag function is enabled, once TagInput is focused (by click or Tab) the tags can be dragged; after the focus leaves TagInput they cannot. The drag handle sits beside its tag and works from the keyboard, see "Keyboard and focus" below. Tags with the same value can be sorted separately.

<script lang="ts">
    import { TagInput } from '@fibrae/semi-ui-svelte';

    let value = $state(['抖音', '火山', '西瓜视频']);
</script>

<TagInput allowDuplicates={false} bind:value draggable placeholder="请输入..." />

API Reference

Props

Methods

class (a string, array or object), style (a string) and native attributes and event handlers land on the root element, except id, name, role, tabindex and the aria-* attributes that describe the input (aria-label, aria-labelledby, aria-describedby, aria-invalid, aria-required, aria-controls, aria-expanded, aria-haspopup, aria-autocomplete, aria-activedescendant, aria-errormessage), which land on the inner input. The lowercase listeners onchange, onfocus, onblur and onkeydown are not native passthroughs; use the callbacks onChange, onFocus, onBlur and onKeyDown above. onclick and onmousedown run in addition to the component's own handling.

Accessibility

ARIA

• TagInput supports the input of aria-label to indicate the function of the TagInput; it lands on the input box, not on the root node;
• The root node has the group role, which holds the input, the tags and the clear button as one control; when disabled it carries aria-disabled="true", otherwise it has no aria-disabled;
• When disabled, the input is natively disabled and the tags are static text without an aria-label; with validateStatus set to error the input carries aria-invalid, and an explicit aria-invalid wins;
• With showClear, tags or input text, and no disabled, a clear button is rendered. It is a native button named "Clear TagInput value" from the locale, shown on hover or while focus is inside the TagInput. From the input, Tab moves to the clear button; Enter or Space clears, as a mouse click does, and the focus goes back to the input. Backspace in the empty input also removes the last tag.

Keyboard and focus

• Enter in the input adds the input text as a tag; with empty input it does nothing. Enter always has its default action prevented, so a TagInput inside a form never submits it.
• Backspace in the empty input removes the last tag.
• A closable tag is a role="button" Tab stop placed before the input; with a tag focused, Backspace or Delete closes it and the focus goes back to the input. When disabled, tags are static text and not focusable.
• With showClear and some content, the clear button follows the input: Tab reaches it, Enter or Space clears, and the focus goes back to the input.
• The active state follows the focus: it starts when the focus comes in from outside (click, Tab or focus()) and ends when it leaves the whole component. Moving the focus between the input, the tags and the clear button is not leaving, so it does not fire focus or blur and does not trigger addOnBlur. While active, tags folded by maxTagCount expand (unless expandRestTagsOnClick is false).
• With draggable and the component active, each tag gets a drag handle that is its own Tab stop, placed before the tag it belongs to. Focus a handle, press Space to pick up, the arrow keys to move and Space to drop; screen readers announce the pick up, moves and drop.

Design Tokens