Notification

System-level sending displays notifications outside the page.

When to use

• When agents perform complex tasks, system-level application notifications can be pushed, allowing the user to stay informed of task progress at any time.
• Subject to operating system notification permission control, only used for weak notifications.

Notes

• Notification refers to system application notifications, which are subject to operating system notification permission control. If system notification permissions are turned off, calling the open method of XNotification will have no effect. System Permission Settings.
• XNotification is implemented by extending window.Notification. If the browser environment does not support Notification, calling XNotification methods will have no effect.
• The notification style and effects of XNotification depend on the current browser environment's support for Notification. For example, the dir attribute will be ignored by most browsers.
• XNotification only manages the closing of notifications within the current instance. After the instance changes (e.g., browser page refresh), it cannot manage or close already sent notifications.

Examples

Hooks usage

Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.

Hooks usage

Hooks usage. Request notification permission first; send only after the user allows it.

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationHooksV2' });

import type { XNotificationOpenArgs } from 'ant-design-x-vue';
import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';

const DescribeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const openData: XNotificationOpenArgs = {
  title: 'Task completed',
  body: 'The task was completed at 13:12',
  icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
  onClick: (event, close) => {
    console.log('onClick', event, close);
    close?.();
  },
  onClose: (event) => {
    console.log('onClose', event);
  },
  onError: (event) => {
    console.log('onError', event);
  },
  onShow: (event) => {
    console.log('onShow', event);
  },
};

const [{ permission }, { open, requestPermission, close }] = notification.useNotification();

defineRender(() => (
  <Flex vertical gap="middle">
    {DescribeInfo[permission.value]}
    <Flex gap="middle">
      <Button
        disabled={permission.value !== 'default'}
        type="primary"
        onClick={() => requestPermission()}
      >
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button
        disabled={permission.value !== 'granted'}
        type="primary"
        onClick={() => open(openData)}
      >
        Open a notification
      </Button>
      <Button danger disabled={permission.value !== 'granted'} onClick={() => close()}>
        Destroy All
      </Button>
    </Flex>
  </Flex>
));
</script>

Hide source

Auto-close delay

Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.

Auto-close delay

Using duration to set the delay for automatic closing of the notification box.

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationDurationV2' });

import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';

const describeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const [{ permission }, { open, requestPermission }] = notification.useNotification();

const openClick = () => {
  open({
    title: 'Task completed',
    body: 'The task was completed at 13:12',
    duration: 4.5,
    icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    onClick: (event, close) => {
      console.log('onClick', event, close);
      close?.();
    },
    onClose: (event) => {
      console.log('onClose', event);
    },
    onError: (event) => {
      console.log('onError', event);
    },
    onShow: (event) => {
      console.log('onShow', event);
    },
  });
};

defineRender(() => (
  <Flex vertical gap="middle">
    {describeInfo[permission.value]}
    <Flex gap="middle">
      <Button disabled={permission.value !== 'default'} type="primary" onClick={() => requestPermission()}>
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button disabled={permission.value !== 'granted'} type="primary" onClick={openClick}>
        Open a notification
      </Button>
    </Flex>
  </Flex>
));
</script>

Hide source

Close a specific notification

Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.

Close a specific notification

Close the notification box with the specified tag.

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationCloseTagV2' });

import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';

const describeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const [{ permission }, { open, close, requestPermission }] = notification.useNotification();

const openClick = () => {
  open({
    title: 'Task completed',
    body: 'The task was completed at 13:12',
    tag: 'tag_task_completed',
    icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    onClick: (event, close) => {
      console.log('onClick', event, close);
      close?.();
    },
    onClose: (event) => {
      console.log('onClose', event);
    },
    onError: (event) => {
      console.log('onError', event);
    },
    onShow: (event) => {
      console.log('onShow', event);
    },
  });
};

defineRender(() => (
  <Flex vertical gap="middle">
    {describeInfo[permission.value]}
    <Flex gap="middle">
      <Button disabled={permission.value !== 'default'} type="primary" onClick={() => requestPermission()}>
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button disabled={permission.value !== 'granted'} type="primary" onClick={openClick}>
        Open a notification
      </Button>
      <Button
        danger
        disabled={permission.value !== 'granted'}
        onClick={() => close(['tag_task_completed'])}
      >
        Destroy tag
      </Button>
    </Flex>
  </Flex>
));
</script>

Hide source

Static methods

Static methods

Static-method usage. Request notification permission before sending.

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationStaticMethodV2' });

import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';
import { ref, onMounted } from 'vue';

const describeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const permission = ref<NotificationPermission>();

onMounted(() => {
  permission.value = notification.permission;
});

const request = async () => {
  const result = await notification.requestPermission();
  permission.value = result;
};

const open = () => {
  notification.open({
    title: 'Task completed',
    body: 'The task was completed at 13:12',
    badge:
      'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    onClick: (event, close) => {
      console.log('onClick', event, close);
      close?.();
    },
    onClose: (event) => {
      console.log('onClose', event);
    },
    onError: (event) => {
      console.log('onError', event);
    },
    onShow: (event) => {
      console.log('onShow', event);
    },
  });
};

const closeAll = () => {
  notification.close();
};

defineRender(() => (
  <Flex vertical gap="middle">
    {permission.value && describeInfo[permission.value]}
    <Flex gap="middle">
      <Button disabled={permission.value !== 'default'} type="primary" onClick={request}>
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button disabled={permission.value !== 'granted'} type="primary" onClick={open}>
        Open a notification
      </Button>
      <Button danger disabled={permission.value !== 'granted'} onClick={closeAll}>
        Destroy All
      </Button>
    </Flex>
  </Flex>
));
</script>

Hide source

API

Successfully sending notifications requires ensuring that the current domain has granted notification permissions.

XNotification

Prop	Description	Type	Default	Version
permission	Indicates whether the current user has granted the current origin permission to display web notifications.	NotificationPermission	-	-
requestPermission	Requests permission from the user to display notifications for the current origin.	() => Promise<NotificationPermission>	-	-
open	Pushes a notification to the user	(config: XNotificationOpenArgs) => void	-	-
close	Closes sent notifications. You can pass a list of tags to close specific notifications; if no parameters are provided, all notifications will be closed	(config?: string[]) => void	-	-

NotificationPermission

type NotificationPermission =
  | 'granted' // 用户已明确授予当前源显示系统通知的权限。
  | 'denied' // 用户已明确拒绝当前源显示系统通知的权限。
  | 'default'; // 用户决定未知；在这种情况下，应用程序的行为就像权限被"拒绝"一样。

XNotificationOpenArgs

type XNotificationOpenArgs = NotificationOptions & {
  title: string;
  onClick?: (event: Event, close?: Notification['close']) => void;
  onClose?: (event: Event) => void;
  onError?: (event: Event) => void;
  onShow?: (event: Event) => void;
  duration?: number;
};

NotificationOptions

interface NotificationOptions {
  badge?: string;
  body?: string;
  data?: any;
  dir?: NotificationDirection;
  icon?: string;
  lang?: string;
  requireInteraction?: boolean;
  silent?: boolean | null;
  tag?: string;
}

useNotification

type useNotification = [
  { permission: NotificationPermission },
  {
    open: XNotification['open'];
    close: XNotification['close'];
    requestPermission: () => Promise<NotificationPermission>;
  },
];

System permission settings

Changing Notification Settings on Windows

The settings path varies across different versions of the Windows system, but you can roughly refer to the path: "Start" menu > "Settings" > "System" > then select "Notifications & actions" on the left side, where you can manage global notifications as well as app notifications.

Changing Notification Settings on Mac

On Mac, use the "Notifications" settings to specify periods when you do not want to be disturbed by notifications and control how notifications appear in the "Notification Center." To change these settings, select the "Apple" menu > "System Settings," then click "Notifications" in the sidebar (you may need to scroll down).

FAQ

Already granted the current source origin permission to display system notifications, and the onShow callback was triggered, so why still can't show the pushed notification?

Notification is a system notification and you need to ensure the device has enabled the corresponding browser app's notification permissions.