Feedback · Notification

Notification

Notifications are used to actively send message notifications to users.

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>

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().

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)
PropertiesInstructionstypeDefault
classClass name of the notification elementstring | object | array
contentContent. A function is rendered as a functional component inside the notification and can injectstring | VNode | (() => VNodeChild)''
directionText direction. A per-notification option only, not part of the global configuration; follows ConfigProvider when omittedltr | rtl
durationAutomatic close delay, no auto-close when set to 0number3
getPopupContainerSpecifies 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
iconTopleft iconstring | VNode | (() => VNodeChild)
idCustom notification id; updates the content when a notification with the same id existsstring
positionPop-up position, one of top、bottom、topLeft、topRight、bottomLeft、bottomRightstringtopRight
showCloseToggle Whether show close buttonbooleantrue
stackStack the notifications at one position once there are more than this many; true means 3, false never stacks. The newest notification at the position decidesboolean | numberfalse
styleInline style of the notification elementStyleValue
themeStyle of background fill, one of light, normalstringnormal
titleTitlestring | VNode | (() => VNodeChild)''
zIndexZ-index value. Applied each time a notification is shown.number1010
onClickCallback function when clicking the notification; lands on the notification element(e: MouseEvent) => void
onCloseCallback function when closing notification, triggered for either auto-close or manually close, once per close() => void
onCloseClickCallback 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.

PropertiesInstructionstypeDefault
bottomBottom, absolute positionnumber | string-
durationAutomatic close delay, no auto-close when set to 0number(second)3
leftLeft, absolute positionnumber | string-
positionPop-up position, one of top、bottom、topLeft、topRight、bottomLeft、bottomRightstringtopRight
rightRight, absolute positionnumber | string-
stackStack the notifications at one position once there are more than this many; true means 3, false never stacksboolean | numberfalse
topTop, absolute positionnumber | string-
zIndexZ-indexnumber1010

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 methods info, success, warning, error, open and close; the first five take the options without type, id, zIndex and getPopupContainer and return the notification id, and close(id) closes one manually. Notifications created by the hook use the built-in defaults and ignore Notification.config(); close(id) removes the notification after its leave animation without calling onClose. <Holder /> is wrapped in a container with data-semi-keep-interactive, so hook notifications stay interactive while a modal layer is open. ConfigProvider and LocaleProvider are component-level provides that the static Notification cannot read; use useNotification() when you need them.

Accessibility

ARIA

  • The role of a notification depends on its type: warning and error are alert; info, success and open are status
  • status notifications are read by a persistent aria-live="polite" region owned by the list; the notification itself is aria-live="off", and only the text of the title and content is announced. warning and error still announce themselves as alert
  • The notification's aria-labelledby is marked as the corresponding notification title

Keyboard and Focus

  • The close button is a native button: focus it with Tab, and activate it with Enter or Space
  • 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

Task completed
400 tasks succeed and 600 failed
Check failed tasks
  • 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

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
$animation_duration-notification-show300ms出现时-动画持续时间
$animation_function-notification-showcubic-bezier(0.62, 0.63, 0, 1.13)出现时-过渡曲线
$animation_delay-notification-show0ms出现时-延迟时间
$animation_duration-notification-hide300ms消失时-动画持续时间
$animation_function-notification-hidecubic-bezier(0.62, 0.63, 0, 1.13)消失时-过渡曲线
$animation_delay-notification-hide0ms消失时-延迟时间
$animation_opacity-notification-show0出现时-初始透明度
$animation_opacity-notification-hide0消失时-结束透明度
$color-notification-bg-defaultvar(--semi-color-bg-3)通知背景色
$color-notification_info-iconvar(--semi-color-info)通知 信息 图标颜色
$color-notification_warning-iconvar(--semi-color-warning)通知 警告 图标颜色
$color-notification_danger-iconvar(--semi-color-danger)通知 危险 图标颜色
$color-notification_success-iconvar(--semi-color-success)通知 成功 图标颜色
$color-notification_title-textvar(--semi-color-text-0)通知 标题 文本颜色
$color-notification_content-textvar(--semi-color-text-1)通知 内容 文本颜色
$color-notification_closeBtn-iconvar(--semi-color-text-2)通知 关闭按钮 图标颜色
$color-notification_warning_light-bgvar(--semi-color-warning-light-default)彩色通知警告背景色
$color-notification_warning_light-bordervar(--semi-color-warning)彩色通知警告描边色
$color-notification_success_light-bgvar(--semi-color-success-light-default)彩色通知成功背景色
$color-notification_success_light-bordervar(--semi-color-success)彩色通知成功描边色
$color-notification_info_light-bgvar(--semi-color-info-light-default)彩色通知信息背景色
$color-notification_info_light-bordervar(--semi-color-info)彩色通知信息描边色
$color-notification_danger_light-bgvar(--semi-color-danger-light-default)彩色通知危险背景色
$color-notification_danger_light-bordervar(--semi-color-danger)彩色通知危险描边色
$color-notification_ambient-bgvar(--semi-color-bg-0)透明背景色叠加层(与bg0保持一致不建议修改)
$width-notification_noticeauto通知宽度
$width-notification_notice_minWidth320px通知最小宽度
$width-notification_notice-icon$width-icon-extra-large通知图标宽度
$width-notification_notice-border1px通知描边宽度
$spacing-notification_list-margin0通知列表外边距
$spacing-notification_list-padding0通知列表内边距
$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-marginRight8px通知卡片内容右侧外边距
$spacing-notification_notice_icon-marginRight$spacing-base-tight通知卡片图标右侧外边距
$radius-notification_noticevar(--semi-border-radius-medium)通知卡片圆角大小
$font-notification_notice_title-fontWeight$font-weight-bold通知卡片标题字重
$font-notification_notice_content-fontWeight$font-weight-regular通知卡片内容字重