Demos
How to import
<script lang="ts">
import { Toast } from '@fibrae/semi-ui-svelte';
</script>
The static methods can only be called in the browser (calling them on the server throws); call them in event handlers. Use Toast.useToast() when you need to read context during component initialization.
Basic Usage
Calling Toast's related methods to show timely feedback to user's operations. It is recommended to set the stack property to apply the stacking style to multiple Toasts on the same screen, and expand them by hovering, which can effectively prevent multiple parallel Toasts at one time.
Code
<script lang="ts">
import { throttle } from 'es-toolkit';
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const opts = {
content: 'Hi, Bytedance dance dance',
duration: 3,
stack: true,
};
const throttleOpts = {
content: 'Hi, Bytedance dance dance',
duration: 10,
onClose: () => throttled.cancel(),
stack: true,
};
const throttled = throttle(() => Toast.info(throttleOpts), 10000, { edges: ['leading'] });
</script>
<div>
<Button onclick={() => Toast.info(opts)}>Display Toast</Button>
<br />
<br />
<Button onclick={throttled}>Throttled Toast</Button>
</div>Other Types
Use different methods to show different Toast including success, warning, error and info.
Code
<script lang="ts">
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const opts = {
content: 'Hi, Bytedance dance dance',
duration: 3,
};
</script>
<Button style="color: var(--semi-color-success)" onclick={() => Toast.success('Hi,Bytedance dance dance')}>Success</Button>
<br />
<br />
<Button type="warning" onclick={() => Toast.warning(opts)}>Warning</Button>
<br />
<br />
<Button type="danger" onclick={() => Toast.error(opts)}>Error</Button>Colored Background
You could use theme for a colored background style. Default is normal.
Code
<script lang="ts">
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const opts = {
content: 'Hi, Bytedance dance dance',
duration: 3,
theme: 'light',
} as const;
</script>
<Button onclick={() => Toast.info(opts)}>Info</Button>
<br />
<br />
<Button style="color: var(--semi-color-success)" onclick={() => Toast.success(opts)}>Success</Button>
<br />
<br />
<Button type="warning" onclick={() => Toast.warning(opts)}>Warning</Button>
<br />
<br />
<Button type="danger" onclick={() => Toast.error(opts)}>Error</Button>Stacking styles
With stack, the Toasts on screen stack once there are more than the threshold, and expand on hover. true sets the threshold to 3, and a number sets a custom one; a stack shows its front 3 layers only.
Code
<script lang="ts">
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const opts = {
content: 'Hi, Bytedance dance dance',
duration: 10,
stack: true,
};
</script>
<Button onclick={() => Toast.info(opts)}>多次点击</Button>Custom Children with Link
Informational feedback
content and icon accept a string or a snippet: define it with {#snippet} in the component and pass it in; components such as Typography can be used directly inside the snippet.
Code
<script lang="ts">
import { Button, Toast, TypographyText } from '@fibrae/semi-ui-svelte';
</script>
{#snippet single()}
<span>
<TypographyText>Hi, Bytedance dance dance</TypographyText>
<TypographyText link style="margin-left: 12px">更多</TypographyText>
</span>
{/snippet}
{#snippet multiLine()}
<div>Hi, Bytedance dance dance</div>
<div style="margin-top: 8px">
<TypographyText link>查看详情</TypographyText>
<TypographyText link style="margin-left: 20px">一会再看</TypographyText>
</div>
{/snippet}
<Button onclick={() => Toast.info({ content: single, duration: 3 })}>Display Toast</Button>
<br />
<br />
<Button onclick={() => Toast.info({ content: multiLine, duration: 3 })}>Display Multi-line Toast</Button>Delay
Use duration to set up time delay. By default it closes after 3 seconds.
Code
<script lang="ts">
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const opts = {
content: 'Hi, Bytedance dance dance',
duration: 10,
};
</script>
<Button onclick={() => Toast.info(opts)}>Close After 10s</Button>Manual Close
Set duration to 0 if you do not want the Toast to close by itself. In this case, it could only be closed manually.
Code
<script lang="ts">
import { Button, Toast } from '@fibrae/semi-ui-svelte';
let toastId: string | null = null;
const destroy = () => {
toastId = null;
};
const opts = {
content: 'Not auto close',
duration: 0,
onClose: destroy,
};
const show = () => {
if (toastId) {
return;
}
toastId = Toast.info(opts);
};
const hide = () => {
if (toastId) {
Toast.close(toastId);
}
destroy();
};
</script>
<Button type="primary" onclick={show}>Show Toast</Button>
<br />
<br />
<Button type="primary" onclick={hide}>Hide Toast</Button>Update Toast Content
Use unique Toast id to update toast content.
Code
<script lang="ts">
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const show = () => {
const id = 'toastid';
Toast.info({ content: 'Update Content By Id', id });
setTimeout(() => {
Toast.success({ content: 'Id By Content Update', id });
}, 1000);
};
</script>
<Button type="primary" onclick={show}>Update Content By Id</Button>Destroy all
Globally Destroy:
Toast.destroyAll()
Consume Context
Call Toast.useToast() during component initialization. The toasts it opens inherit the context, ConfigProvider and locale of the calling component, and no Holder is needed. They are mounted under document.body and removed when the calling component is destroyed.
Toast.useToast() returns the toast object: info, success, warning, error and open take the Options without type, id, top, bottom, left, right, zIndex and getPopupContainer and return the toastId; close(toastId) closes one manually. A snippet passed as content or icon can call getContext to read the calling component's context. The values of ConfigProvider and LocaleProvider cannot be read by the static Toast; use useToast() when you need them.
Code
<script lang="ts">
import { getContext, setContext } from 'svelte';
import { Button, Toast } from '@fibrae/semi-ui-svelte';
const reachableKey = Symbol('reachable');
setContext(reachableKey, 'Light');
const toast = Toast.useToast();
</script>
<!-- The snippet renders inside the toast list mounted with this component's contexts, so it reads the context set above -->
{#snippet reachable()}ReachableContext: {getContext(reachableKey)}{/snippet}
<div>
<Button onclick={() => toast.success({ duration: 0, content: reachable })}>Hook Toast</Button>
</div>Create Toast with different configurations
ToastFactory.create(config) => Toast
If you need Toast with different configs in your application, you can use ToastFactory.create(config)to create a new Toast:
Code
<script lang="ts">
import { onDestroy } from 'svelte';
import { Button, Toast, ToastFactory } from '@fibrae/semi-ui-svelte';
const ToastInCustomContainer = ToastFactory.create({
getPopupContainer: () => document.getElementById('custom-toast-container') as HTMLElement,
});
onDestroy(() => ToastInCustomContainer.destroyAll());
</script>
<div>
<Button onclick={() => Toast.info('Toast')}>Default Toast</Button>
<br />
<br />
<Button onclick={() => ToastInCustomContainer.info('Toast in some container')}>Toast in custom container</Button>
<div id="custom-toast-container">custom container</div>
</div>API Reference
The static methods provided are as follows: Display: You can pass in options object or string directly. Methods return the value of toastId: const toastId = Toast.info({ /*...options*/ })
The global configuration is set before any method call, and takes effect only once
Toast.config(config)Toast.resetConfig()restores the global configuration to its defaults; only toasts shown afterwards are affected. An instance created byToastFactory.create(config)is restored to theconfigit was created with
Show Toast Directly
Toast.info(options || string)Toast.error(options || string)Toast.warning(options || string)Toast.success(options || string)
info error warning success return the toastId, can be used for manually closing
Toast.close(toastId)Close Manually
Options
Toast Options supports the following APIs as well as the APIs in Config
| Property | Description | Type | Default |
|---|---|---|---|
| content | Toast content, a string or a snippet; the snippet runs where the toast renders | string | Snippet | '' |
| icon | Custom icon, a string or a snippet, replacing the icon of type | string | Snippet | |
| showClose | Whether to show the close button | boolean | true |
| textMaxWidth | Maximum width of the content | number | string | 450 |
| onClose | Callback function when the toast closes | () => void | |
| stack | Stack the toasts on screen once there are more than this many; true means 3, false never stacks | boolean | number | false |
| id | Custom ToastId; a toast with the same id is updated | string | |
| motion | Whether to animate entering and leaving | boolean | true |
| class | Class name | string | object | array | |
| style | Inline style, a string only | string |
class, style and undeclared options (such as data-* and aria-*) land on .semi-toast, in stack mode too.
Config
The following API supports global configuration to change the default configuration of the current Toast
| Properties | Instructions | type | Default |
|---|---|---|---|
| bottom | Pop-up position bottom | number | string | - |
| left | Pop-up position left | number | string | - |
| right | Pop-up position right | number | string | - |
| top | Pop-up position top | number | string | - |
| zIndex | Z-index value | number | 1010 |
| theme | Style of background fill, one of light, normal | string | normal |
| duration | Automatic close delay, no auto-close when set to 0 | number | 3 |
| getPopupContainer | Specifies the parent DOM, and the bullet layer will be rendered to the DOM, you need to set container and inner .semi-toast-wrapper 'position: relative` This will change the DOM tree position, but not the view's rendering position. | () => HTMLElement | () => document.body |
Accessibility
ARIA
- The role of Toast depends on its type:
alertforwarninganderror,statusforinfo,successand a Toast withouttype statusToasts are read by a persistentaria-live="polite"region owned by the list; the Toast itself isaria-live="off", and only the text ofcontentis announced.warninganderrorstill announce themselves asalert
Keyboard and Focus
- The close button is a native
button: focus it withTab, and activate it withEnterorSpace - A Toast does not take focus when it appears
- When the pointer or keyboard focus enters a Toast, its auto-close timer pauses and a stack expands; both resume when it leaves
Content Guidelines
- Keep it simple
- Do not use periods at the end of sentences
- Explain using the noun + verb format
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
| Language added | New language has been added successfully |
| Ticket transfer failed | Can't transfer ticket |
- Provide prompt message for action
- only provide one action
- Don't use actions like "read" like OK, Got it, Dismiss, Cancel
| ✅ Recommended usage | ❌ Deprecated usage |
|---|---|
Ticket transfer failed Retry | Ticket transfer failed Dismiss |
Design Tokens
| Sass variable | Value | Usage |
|---|---|---|
| $animation_duration-toast-show | 300ms | |
| $animation_duration-toast-hide | 300ms | |
| $animation_function-toast-show | cubic-bezier(0.22, 0.57, 0.02, 1.2) | |
| $animation_function-toast-hide | cubic-bezier(0.22, 0.57, 0.02, 1.2) | |
| $animation_delay-toast-show | 0s | |
| $animation_delay-toast-hide | 0s | |
| $animation_opacity-toast-show | 0 | |
| $animation_opacity-toast-hide | 0 | |
| $animation_transform_translateY-toast-show | -100% | |
| $animation_transform_translateY-toast-hide | -100% | |
| $animation_duration-toast-stack | 300ms | |
| $animation_function-toast-stack | cubic-bezier(0.22, 0.57, 0.02, 1.2) | |
| $color-toast-bg-default | var(--semi-color-bg-3) | 提示背景颜色 - 默认 |
| $color-toast-text-default | var(--semi-color-text-0) | 提示文字颜色 - 默认 |
| $color-toast_warning-icon | var(--semi-color-warning) | 警告提示图标颜色 |
| $color-toast_success-icon | var(--semi-color-success) | 成功提示图标颜色 |
| $color-toast_info-icon | var(--semi-color-info) | 通知提示图标颜色 |
| $color-toast_danger-icon | var(--semi-color-danger) | 错误提示图标颜色 |
| $color-toast_warning_light-bg | var(--semi-color-warning-light-default) | 多色样式 警告提示背景颜色 |
| $color-toast_warning_light-icon | $color-toast_warning-icon | 多色样式 警告提示图标颜色 |
| $color-toast_warning_light-border | var(--semi-color-warning) | 多色样式 警告提示描边颜色 |
| $color-toast_success_light-bg | var(--semi-color-success-light-default) | 多色样式 成功提示背景颜色 |
| $color-toast_success_light-icon | $color-toast_success-icon | 多色样式 成功提示图标颜色 |
| $color-toast_success_light-border | var(--semi-color-success) | 多色样式 成功提示描边颜色 |
| $color-toast_info_light-bg | var(--semi-color-info-light-default) | 多色样式 通知提示背景颜色 |
| $color-toast_info_light-icon | $color-toast_info-icon | 多色样式 通知提示图标颜色 |
| $color-toast_info_light-border | var(--semi-color-info) | 多色样式 通知提示描边颜色 |
| $color-toast_danger_light-bg | var(--semi-color-danger-light-default) | 多色样式 错误提示背景颜色 |
| $color-toast_danger_light-icon | $color-toast_danger-icon | 多色样式 错误提示图标颜色 |
| $color-toast_danger_light-border | var(--semi-color-danger) | 多色样式 错误提示描边颜色 |
| $spacing-toast_wrapper-top | 0 | 通知容器顶部位置 |
| $spacing-toast_content-paddingY | $spacing-base-tight | 通知内容垂直内边距 |
| $spacing-toast_content-paddingX | $spacing-tight | 通知内容水平内边距 |
| $spacing-toast_content-paddingTop | $spacing-toast_content-paddingY | 通知内容 top 内边距 |
| $spacing-toast_content-paddingBottom | $spacing-toast_content-paddingY | 通知内容 bottom 内边距 |
| $spacing-toast_content-paddingLeft | $spacing-toast_content-paddingX | 通知内容 left 内边距 |
| $spacing-toast_content-paddingRight | $spacing-toast_content-paddingX | 通知内容 right 内边距 |
| $spacing-toast_content-margin | $spacing-base-tight | 通知内容外边距 |
| $spacing-toast_content_close_btn-marginTop | -2px | 通知关闭按钮顶部外边距 |
| $spacing-toast_content_text-marginLeft | $spacing-base-tight | 通知文本左侧外边距 |
| $spacing-toast_content_text-marginRight | $spacing-base-tight | 通知文本右侧外边距 |
| $spacing-toast-perspective-originY | 280px | 通知透视原点 Y 轴位置 |
| $spacing-toast-perspective | 280px | 通知透视距离 |
| $width-toast_wrapper | 100% | 通知容器整体宽度 |
| $width-toast_light-border | 1px | 多色样式 通知描边宽度 |
| $radius-toast_content | var(--semi-border-radius-medium) | 通知圆角 |
| $font-toast_content-fontWeight | $font-weight-bold | 通知文本字重 |