Feedback · Notification

Notification

Notifications are used to actively send message notifications to users.

Demos

How to import

import { Notification } from '@fibrous/semi-ui-react';

Basic Usage

Close after 3 seconds.

Code
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    return (
        <Button
            onClick={() =>
                Notification.open({
                    title: 'Hi, Bytedance',
                    content: 'ies dance dance dance',
                    duration: 3,
                })
            }
        >
            Display Notification
        </Button>
    );
}

Position

Use position to set pop up position, supporting one of: top、bottom、topLeft、topRight(default)、bottomLeft、bottomRight。



Code
import { Notification, Button, ButtonGroup } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    let opts = {
        duration: 3,
        position: 'topRight',
        content: 'semi-ui-notification',
        title: 'Hi bytedance',
    } as const;

    return (
        <>
            <ButtonGroup>
                <Button onClick={() => Notification.info({ ...opts, position: 'top' })}>top</Button>
                <Button onClick={() => Notification.info({ ...opts, position: 'topLeft' })}>topLeft</Button>
                <Button onClick={() => Notification.info(opts)}>topRight</Button>
            </ButtonGroup>
            <br />
            <br />
            <ButtonGroup>
                <Button onClick={() => Notification.info({ ...opts, position: 'bottom' })}>bottom</Button>
                <Button onClick={() => Notification.info({ ...opts, position: 'bottomRight' })}>bottomRight</Button>
                <Button onClick={() => Notification.info({ ...opts, position: 'bottomLeft' })}>bottomLeft</Button>
            </ButtonGroup>
        </>
    );
}

With Icons

Use different methods to show Notification with icons or you can pass in icon for customized icon.

默认的图标
自定义图标
Code
import { IconToutiaoLogo, IconVigoLogo } from '@fibrous/semi-icons-react';
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    let opts = {
        title: 'Hi, Bytedance',
        content: 'ies dance dance dance',
        duration: 3,
    };

    return (
        <>
            <h5>默认的图标</h5>
            <Button type="primary" onClick={() => Notification.success(opts)} style={{ margin: 4 }}>
                Success
            </Button>
            <Button onClick={() => Notification.info(opts)} style={{ margin: 4 }}>
                Info
            </Button>
            <Button type="warning" onClick={() => Notification.warning(opts)} style={{ margin: 4 }}>
                Warning
            </Button>
            <Button type="danger" onClick={() => Notification.error(opts)} style={{ margin: 4 }}>
                Error
            </Button>
            <h5>自定义图标</h5>
            <Button
                aria-label="Toutiao 图标通知"
                icon={<IconToutiaoLogo />}
                style={{ marginRight: 5 }}
                onClick={() =>
                    Notification.info({
                        ...opts,
                        icon: <IconToutiaoLogo style={{ color: 'red' }} />,
                    })
                }
            />
            <Button aria-label="Vigo 图标通知" icon={<IconVigoLogo />} style={{ marginRight: 5 }} onClick={() => Notification.info({ ...opts, icon: <IconVigoLogo /> })} />
            <Button aria-label="粉色 Vigo 图标通知" icon={<IconVigoLogo />} onClick={() => Notification.info({ ...opts, icon: <IconVigoLogo style={{ color: 'pink' }} /> })} />
        </>
    );
}

Colored Background

You could use theme for a colored background style. Default is normal.







Code
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    let opts = {
        title: 'Hi, Bytedance',
        content: 'Hi, Bytedance dance dance',
        duration: 3,
        theme: 'light',
    } as const;

    return (
        <>
            <Button onClick={() => Notification.info(opts)}>Info</Button>
            <br />
            <br />
            <Button onClick={() => Notification.success(opts)}>Success</Button>
            <br />
            <br />
            <Button type="warning" onClick={() => Notification.warning(opts)}>
                Warning
            </Button>
            <br />
            <br />
            <Button type="danger" onClick={() => Notification.error(opts)}>
                Error
            </Button>
        </>
    );
}

Use with Typography to create operation links for more complicated situations.

Delay

Use duration to set up time delay. By default it closes after 3 seconds.

Code
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    let opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 10,
    };

    return <Button onClick={() => Notification.info(opts)}>Close After 10s</Button>;
}

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
import { useState } from 'react';
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    let opts = {
        content: 'Not auto close',
        title: 'Hi',
        duration: 0,
    };
    const [ids, setIds] = useState<string[]>([]);
    function show() {
        let id = Notification.info(opts);
        setIds([...ids, id]);
    }
    function hide() {
        let idsTmp = [...ids];
        const first = idsTmp.shift();
        if (first) {
            Notification.close(first);
        }
        setIds(idsTmp);
    }
    return (
        <>
            <Button type="primary" onClick={show}>
                Show Notification
            </Button>
            <br />
            <br />
            <Button type="primary" onClick={hide}>
                Hide Notification
            </Button>
        </>
    );
}

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
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    return (
        <Button
            onClick={() => {
                Notification.info({ title: 'Hi', content: 'Hi, Bytedance dance dance', duration: 10, stack: true });
            }}
        >
            Click multiple times
        </Button>
    );
}

Update content

You can use id to update notification content.

Code
import { Notification, Button } from '@fibrous/semi-ui-react';

export default function NotificationDemo() {
    return (
        <Button
            onClick={() => {
                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);
            }}
        >
            Display Notification
        </Button>
    );
}

Consume Context

Use Notification.useNotification to create a contextHolder that can access context. Notifications render where the contextHolder is placed and enter and leave with the same animations as the static methods.

Code
import { createContext, useState } from 'react';
import { Notification, Button, Space } from '@fibrous/semi-ui-react';

const ReachableContext = createContext('');

export default function NotificationDemo() {
    const [notification, contextHolder] = Notification.useNotification();
    const [ids, setIds] = useState<string[]>([]);

    function show() {
        const id = notification.info({
            title: 'Hook Notification',
            content: <ReachableContext.Consumer>{(name) => `ReachableContext: ${name}`}</ReachableContext.Consumer>,
            duration: 0,
        });
        setIds([...ids, id]);
    }

    function hide() {
        const [first, ...rest] = ids;
        if (first) {
            notification.close(first);
        }
        setIds(rest);
    }

    return (
        <ReachableContext.Provider value="Light">
            <Space>
                <Button onClick={show}>Show Notification</Button>
                <Button onClick={hide}>Hide Notification</Button>
            </Space>
            {contextHolder}
        </ReachableContext.Provider>
    );
}

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
classNameClass name of the notification elementstring
contentContentReactNode''
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.() => HTMLElement() => document.body
iconTopleft iconReactNode
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 elementCSSProperties
themeStyle of background fill, one of light, normalstringnormal
titleTitleReactNode''
zIndexZ-index value. Only take effect for the first time.number1010
onClickCallback function when clicking the notification(e: event) => 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

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()
    When you need access Context, you could use Notification.useNotification to create a contextHolder and insert to corresponding DOM tree. Notification created by hooks will be able to access the context where contextHolder is inserted. Hook Notification has following methods: info, success, warning, error, open, close; the first five take options without type, id, zIndex and getPopupContainer, and return the notification id. Notifications created by hooks use the built-in defaults and ignore Notification.config(); close(id) removes the notification after its leave animation without calling onClose. The contextHolder is wrapped in a container with data-semi-keep-interactive, so hook notifications stay interactive while a modal layer is open.

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通知卡片内容字重