Demos
How to import
<script setup lang="ts">
import { Notification } from '@fibrous/semi-ui-vue';
</script>
Static methods render outside the component tree. Optionally call app.use(Notification): static notifications then render with that app's context, so they can read values from app.provide() and globally registered components. The static methods of Toast, Notification and Modal share this record, so installing any one of them applies to all three; when several apps install, the last one wins.
Basic Usage
Close after 3 seconds.
Code
<script setup lang="ts">
import { Button, Notification } from '@fibrous/semi-ui-vue';
const opts = {
title: 'Hi, Bytedance',
content: 'ies dance dance dance',
duration: 3,
};
</script>
<template>
<Button @click="Notification.open(opts)">Display Notification</Button>
</template>Position
Use position to set pop up position, supporting one of: top、bottom、topLeft、topRight(default)、bottomLeft、bottomRight。
Code
<script setup lang="ts">
import { Button, ButtonGroup, Notification } from '@fibrous/semi-ui-vue';
const opts = {
duration: 3,
position: 'topRight',
content: 'semi-ui-notification',
title: 'Hi bytedance',
} as const;
</script>
<template>
<ButtonGroup>
<Button @click="Notification.info({ ...opts, position: 'top' })">top</Button>
<Button @click="Notification.info({ ...opts, position: 'topLeft' })">topLeft</Button>
<Button @click="Notification.info(opts)">topRight</Button>
</ButtonGroup>
<br />
<br />
<ButtonGroup>
<Button @click="Notification.info({ ...opts, position: 'bottom' })">bottom</Button>
<Button @click="Notification.info({ ...opts, position: 'bottomRight' })">bottomRight</Button>
<Button @click="Notification.info({ ...opts, position: 'bottomLeft' })">bottomLeft</Button>
</ButtonGroup>
</template>With Icons
Use different methods to show Notification with icons or you can pass in icon for customized icon.
默认的图标
自定义图标
Code
<script setup lang="ts">
import { h } from 'vue';
import { IconToutiaoLogo, IconVigoLogo } from '@fibrous/semi-icons-vue';
import { Button, Notification } from '@fibrous/semi-ui-vue';
const opts = {
title: 'Hi, Bytedance',
content: 'ies dance dance dance',
duration: 3,
};
// icon is a VNode or a render function, which a template cannot express
const showIcon = (icon: typeof IconVigoLogo, color?: string) => Notification.info({ ...opts, icon: h(icon, color ? { style: { color } } : null) });
</script>
<template>
<h5>默认的图标</h5>
<Button :style="{ margin: '4px' }" type="primary" @click="Notification.success(opts)">Success</Button>
<Button :style="{ margin: '4px' }" @click="Notification.info(opts)">Info</Button>
<Button :style="{ margin: '4px' }" type="warning" @click="Notification.warning(opts)">Warning</Button>
<Button :style="{ margin: '4px' }" type="danger" @click="Notification.error(opts)">Error</Button>
<h5>自定义图标</h5>
<Button aria-label="Toutiao 图标通知" :style="{ marginRight: '5px' }" @click="showIcon(IconToutiaoLogo, 'red')">
<template #icon>
<IconToutiaoLogo />
</template>
</Button>
<Button aria-label="Vigo 图标通知" :style="{ marginRight: '5px' }" @click="showIcon(IconVigoLogo)">
<template #icon>
<IconVigoLogo />
</template>
</Button>
<Button aria-label="粉色 Vigo 图标通知" @click="showIcon(IconVigoLogo, 'pink')">
<template #icon>
<IconVigoLogo />
</template>
</Button>
</template>Colored Background
You could use theme for a colored background style. Default is normal.
Code
<script setup lang="ts">
import { Button, Notification } from '@fibrous/semi-ui-vue';
const opts = {
title: 'Hi, Bytedance',
content: 'Hi, Bytedance dance dance',
duration: 3,
theme: 'light',
} as const;
</script>
<template>
<Button @click="Notification.info(opts)">Info</Button>
<br />
<br />
<Button @click="Notification.success(opts)">Success</Button>
<br />
<br />
<Button type="warning" @click="Notification.warning(opts)">Warning</Button>
<br />
<br />
<Button type="danger" @click="Notification.error(opts)">Error</Button>
</template>Custom Children with Link
Use with Typography to create operation links for more complicated situations.
title, content and icon accept a string, a VNode, or a function returning VNodeChild; the Typography text in the demo below is built with h().
Code
<script setup lang="ts">
import { h } from 'vue';
import { Button, Notification, Typography } from '@fibrous/semi-ui-vue';
const { Text } = Typography;
// content is a VNode or a render function, which a template cannot express
const opts = {
title: 'This is a title',
content: () => [h('div', 'Hi, Bytedance dance dance'), h('div', { style: { marginTop: '8px' } }, [h(Text, { link: true }, () => '查看详情'), h(Text, { link: true, style: { marginLeft: '20px' } }, () => '一会再看')])],
duration: 3,
};
</script>
<template>
<Button @click="Notification.info(opts)">Display Notification</Button>
</template>Delay
Use duration to set up time delay. By default it closes after 3 seconds.
Code
<script setup lang="ts">
import { Button, Notification } from '@fibrous/semi-ui-vue';
const opts = {
content: 'Hi, Bytedance dance dance',
duration: 10,
};
</script>
<template>
<Button @click="Notification.info(opts)">Close After 10s</Button>
</template>Manual Close
Set duration to 0 if you do not want the Notification to close by itself. In this case, it could only be closed manually.
Code
<script setup lang="ts">
import { ref } from 'vue';
import { Button, Notification } from '@fibrous/semi-ui-vue';
const opts = {
content: 'Not auto close',
title: 'Hi',
duration: 0,
};
const ids = ref<string[]>([]);
function show() {
ids.value.push(Notification.info(opts));
}
function hide() {
const first = ids.value.shift();
if (first) {
Notification.close(first);
}
}
</script>
<template>
<Button type="primary" @click="show">Show Notification</Button>
<br />
<br />
<Button type="primary" @click="hide">Hide Notification</Button>
</template>Stack
With stack, the notifications at one position 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 setup lang="ts">
import { Button, Notification } from '@fibrous/semi-ui-vue';
const opts = {
title: 'Hi',
content: 'Hi, Bytedance dance dance',
duration: 10,
stack: true,
};
</script>
<template>
<Button @click="Notification.info(opts)">Click multiple times</Button>
</template>Update content
You can use id to update notification content.
Code
<script setup lang="ts">
import { Button, Notification } from '@fibrous/semi-ui-vue';
function show() {
const id = Notification.open({
title: 'Hi, Bytedance',
content: 'ies dance dance dance',
duration: 3,
});
setTimeout(() => {
Notification.open({
title: 'Hi, Bytedance',
content: 'updated',
duration: 10,
id,
});
}, 1000);
}
</script>
<template>
<Button @click="show">Display Notification</Button>
</template>Consume Context
Use Notification.useNotification() to create a Holder that can access context. Notifications render where <Holder /> is placed, inherit the provides, ConfigProvider and locale there, and enter and leave with the same animations as the static methods. A function passed as content, icon or title is rendered as a functional component inside the notification, so it can inject.
Code
<script setup lang="ts">
import { inject, provide, ref, type InjectionKey } from 'vue';
import { Button, Notification, Space } from '@fibrous/semi-ui-vue';
const reachableKey: InjectionKey<string> = Symbol('reachable');
provide(reachableKey, 'Light');
const [notification, Holder] = Notification.useNotification();
const ids = ref<string[]>([]);
// The function is rendered as a functional component inside the notification, so it can inject from where Holder sits
const content = () => `ReachableContext: ${inject(reachableKey)}`;
function show() {
ids.value.push(notification.info({ title: 'Hook Notification', content, duration: 0 }));
}
function hide() {
const first = ids.value.shift();
if (first) {
notification.close(first);
}
}
</script>
<template>
<Space>
<Button @click="show">Show Notification</Button>
<Button @click="hide">Hide Notification</Button>
</Space>
<Holder />
</template>API Reference
The static methods provided are as follows:
Display: You can pass in options object directly. Methods return the value of id: const id = Notification.open({ /*...options*/ })
Notification.open({content: 'message', duration: 3})Notification.info({content: 'message', duration: 3})Notification.error({content: 'message', duration: 3})Notification.warning({content: 'message', duration: 3})Notification.success({content: 'message', duration: 3})
Close Manually (id is the return value of the display methods)
Notification.close(id)
| Properties | Instructions | type | Default |
|---|---|---|---|
| class | Class name of the notification element | string | object | array | |
| content | Content. A function is rendered as a functional component inside the notification and can inject | string | VNode | (() => VNodeChild) | '' |
| direction | Text direction. A per-notification option only, not part of the global configuration; follows ConfigProvider when omitted | ltr | rtl | |
| 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 'position: relative` This will change the DOM tree position, but not the view's rendering position. Only takes effect when the container is first created. | () => HTMLElement | () => document.body |
| icon | Topleft icon | string | VNode | (() => VNodeChild) | |
| id | Custom notification id; updates the content when a notification with the same id exists | string | |
| position | Pop-up position, one of top、bottom、topLeft、topRight、bottomLeft、bottomRight | string | topRight |
| showClose | Toggle Whether show close button | boolean | true |
| stack | Stack the notifications at one position once there are more than this many; true means 3, false never stacks. The newest notification at the position decides | boolean | number | false |
| style | Inline style of the notification element | StyleValue | |
| theme | Style of background fill, one of light, normal | string | normal |
| title | Title | string | VNode | (() => VNodeChild) | '' |
| zIndex | Z-index value. Applied each time a notification is shown. | number | 1010 |
| onClick | Callback function when clicking the notification; lands on the notification element | (e: MouseEvent) => void | |
| onClose | Callback function when closing notification, triggered for either auto-close or manually close, once per close | () => void | |
| onCloseClick | Callback function when actively clicking on the close button | (id: string) => void |
onClick, onClose and onCloseClick keep their key names in the options and do not use emits.
The global configuration is set before any method call, and takes effect only once:
Notification.config(config)Notification.resetConfig()restores the global configuration to its defaults; only notifications shown afterwards are affected
Notification.config does not accept direction; text direction is an option of a single notification only.
| Properties | Instructions | type | Default |
|---|---|---|---|
| bottom | Bottom, absolute position | number | string | - |
| duration | Automatic close delay, no auto-close when set to 0 | number(second) | 3 |
| left | Left, absolute position | number | string | - |
| position | Pop-up position, one of top、bottom、topLeft、topRight、bottomLeft、bottomRight | string | topRight |
| right | Right, absolute position | number | string | - |
| stack | Stack the notifications at one position once there are more than this many; true means 3, false never stacks | boolean | number | false |
| top | Top, absolute position | number | string | - |
| zIndex | Z-index | number | 1010 |
Globally Destroy:
Notification.destroyAll()
Hook Notification
Notification.useNotification()
Returns a tuple[notification, Holder]; place<Holder />in the corresponding node. Notifications created by the hook can access the context where<Holder />is placed. The notification object has the methodsinfo,success,warning,error,openandclose; the first five take the options withouttype,id,zIndexandgetPopupContainerand return the notification id, andclose(id)closes one manually. Notifications created by the hook use the built-in defaults and ignoreNotification.config();close(id)removes the notification after its leave animation without callingonClose.<Holder />is wrapped in a container withdata-semi-keep-interactive, so hook notifications stay interactive while a modal layer is open. ConfigProvider and LocaleProvider are component-level provides that the staticNotificationcannot read; useuseNotification()when you need them.
Accessibility
ARIA
- The
roleof a notification depends on its type:warninganderrorarealert;info,successandopenarestatus statusnotifications are read by a persistentaria-live="polite"region owned by the list; the notification itself isaria-live="off", and only the text of the title and content is announced.warninganderrorstill announce themselves asalert- The notification's
aria-labelledbyis marked as the corresponding notification title
Keyboard and Focus
- The close button is a native
button: focus it withTab, and activate it withEnterorSpace - A notification does not take focus when it appears
- When the pointer or keyboard focus enters a notification, its auto-close timer pauses and a stack expands; both resume when it leaves
Content Guidelines
- Title
- Explain in clear and concise language
- Avoid punctuation such as commas, periods, etc.
- Text
- On the premise of complete information transmission, try to compress the text to 1-2 sentences
- A detailed description or explanation of the title, rather than a repetition of the title
- Use correct punctuation, commas within sentences and periods between sentences
- Operate
- The copy needs to show the specific meaning of the operation
Design Tokens
| Sass variable | Value | Usage |
|---|---|---|
| $animation_duration-notification-show | 300ms | 出现时-动画持续时间 |
| $animation_function-notification-show | cubic-bezier(0.62, 0.63, 0, 1.13) | 出现时-过渡曲线 |
| $animation_delay-notification-show | 0ms | 出现时-延迟时间 |
| $animation_duration-notification-hide | 300ms | 消失时-动画持续时间 |
| $animation_function-notification-hide | cubic-bezier(0.62, 0.63, 0, 1.13) | 消失时-过渡曲线 |
| $animation_delay-notification-hide | 0ms | 消失时-延迟时间 |
| $animation_opacity-notification-show | 0 | 出现时-初始透明度 |
| $animation_opacity-notification-hide | 0 | 消失时-结束透明度 |
| $color-notification-bg-default | var(--semi-color-bg-3) | 通知背景色 |
| $color-notification_info-icon | var(--semi-color-info) | 通知 信息 图标颜色 |
| $color-notification_warning-icon | var(--semi-color-warning) | 通知 警告 图标颜色 |
| $color-notification_danger-icon | var(--semi-color-danger) | 通知 危险 图标颜色 |
| $color-notification_success-icon | var(--semi-color-success) | 通知 成功 图标颜色 |
| $color-notification_title-text | var(--semi-color-text-0) | 通知 标题 文本颜色 |
| $color-notification_content-text | var(--semi-color-text-1) | 通知 内容 文本颜色 |
| $color-notification_closeBtn-icon | var(--semi-color-text-2) | 通知 关闭按钮 图标颜色 |
| $color-notification_warning_light-bg | var(--semi-color-warning-light-default) | 彩色通知警告背景色 |
| $color-notification_warning_light-border | var(--semi-color-warning) | 彩色通知警告描边色 |
| $color-notification_success_light-bg | var(--semi-color-success-light-default) | 彩色通知成功背景色 |
| $color-notification_success_light-border | var(--semi-color-success) | 彩色通知成功描边色 |
| $color-notification_info_light-bg | var(--semi-color-info-light-default) | 彩色通知信息背景色 |
| $color-notification_info_light-border | var(--semi-color-info) | 彩色通知信息描边色 |
| $color-notification_danger_light-bg | var(--semi-color-danger-light-default) | 彩色通知危险背景色 |
| $color-notification_danger_light-border | var(--semi-color-danger) | 彩色通知危险描边色 |
| $color-notification_ambient-bg | var(--semi-color-bg-0) | 透明背景色叠加层(与bg0保持一致不建议修改) |
| $width-notification_notice | auto | 通知宽度 |
| $width-notification_notice_minWidth | 320px | 通知最小宽度 |
| $width-notification_notice-icon | $width-icon-extra-large | 通知图标宽度 |
| $width-notification_notice-border | 1px | 通知描边宽度 |
| $spacing-notification_list-margin | 0 | 通知列表外边距 |
| $spacing-notification_list-padding | 0 | 通知列表内边距 |
| $spacing-notification_notice-paddingTop | $spacing-base | 通知卡片顶部内边距 |
| $spacing-notification_notice-paddingRight | $spacing-base-tight | 通知卡片右侧内边距 |
| $spacing-notification_notice-paddingBottom | $spacing-base | 通知卡片底部内边距 |
| $spacing-notification_notice-paddingLeft | $spacing-base-loose | 通知卡片左侧内边距 |
| $spacing-notification_notice-margin | $spacing-base-loose | 通知卡片外边距 |
| $spacing-notification_notice_title-marginBottom | $spacing-extra-tight | 通知卡片标题底部外边距 |
| $spacing-notification_notice_content_wrapper-marginRight | 8px | 通知卡片内容右侧外边距 |
| $spacing-notification_notice_icon-marginRight | $spacing-base-tight | 通知卡片图标右侧外边距 |
| $radius-notification_notice | var(--semi-border-radius-medium) | 通知卡片圆角大小 |
| $font-notification_notice_title-fontWeight | $font-weight-bold | 通知卡片标题字重 |
| $font-notification_notice_content-fontWeight | $font-weight-regular | 通知卡片内容字重 |