@rc-component/notification

_{Part of the Ant Design ecosystem.}

🔔 Hook-based React notification primitives for stacked, animated, and accessible notices.

English | 简体中文

Highlights

• useNotification hook returning an API and React holder element.
• Top, bottom, left, and right placements with max-count limiting.
• Closable notices, duration timers, progress display, hover pause, and stacked layout.
• Custom motion, semantic classNames / styles, progress component override, and provider-level classes.
• TypeScript definitions for notification config, API, list config, and progress props.
• Used by Ant Design as the shared notification foundation.

Install

npm install @rc-component/notification

Usage

import { useNotification } from '@rc-component/notification';

export default () => {
  const [api, holder] = useNotification();

  return (
    <>
      {holder}
      <button
        type="button"
        onClick={() => {
          api.open({
            key: 'welcome',
            title: 'Notification',
            description: 'This notice is rendered by @rc-component/notification.',
            closable: true,
          });
        }}
      >
        Open
      </button>
    </>
  );
};

import { NotificationProvider, useNotification } from '@rc-component/notification';

const Demo = () => {
  const [api, holder] = useNotification({
    placement: 'topRight',
    maxCount: 3,
    showProgress: true,
    pauseOnHover: true,
    stack: true,
  });

  return (
    <>
      {holder}
      <button type="button" onClick={() => api.open({ title: 'Queued' })}>
        Add
      </button>
    </>
  );
};

export default () => (
  <NotificationProvider classNames={{ notice: 'custom-notice' }}>
    <Demo />
  </NotificationProvider>
);

Examples

Run the local dumi site:

npm install
npm start

Then open http://localhost:8000.

API

useNotification

const [api, holder] = useNotification(config);

Property	Type	Default	Description
className	(placement: Placement) => string	-	Class name for each placement container.
classNames	NotificationClassNames	-	Semantic class names for notice and list slots.
closable	boolean | { closeIcon?: ReactNode; onClose?: () => void }	-	Shared closable config for opened notices.
components	{ progress?: ComponentType<NotificationProgressProps> }	-	Component overrides.
duration	number | false | null	4.5	Auto-close delay in seconds. Use false or 0 to disable.
getContainer	() => HTMLElement | ShadowRoot	() => document.body	Notification portal container.
maxCount	number	-	Maximum notices to keep. Oldest notices are dropped.
motion	CSSMotionProps | (placement) => CSSMotionProps	-	Motion config for notice transitions.
pauseOnHover	boolean	true	Pause auto-close timer while hovering.
placement	Placement	topRight	Default placement for opened notices.
prefixCls	string	rc-notification	Class name prefix.
renderNotifications	(node, info) => ReactElement	-	Customize the rendered notification tree.
showProgress	boolean	false	Show auto-close progress for opened notices.
stack	boolean | StackConfig	false	Enable stacked notification layout.
style	(placement: Placement) => CSSProperties	-	Inline style for each placement container.
styles	NotificationStyles	-	Semantic styles for notice and list slots.
onAllRemoved	() => void	-	Triggered after all notices are removed.

NotificationAPI

Method	Type	Description
open	(config: Partial<NotificationListConfig>) => void	Open or update a notice.
close	(key: React.Key) => void	Close a notice by key.
destroy	() => void	Remove all notices.

NotificationListConfig

Property	Type	Default	Description
actions	ReactNode	-	Extra action content.
className	string	-	Class name for the notice.
classNames	NotificationClassNames	-	Semantic class names for notice slots.
closable	boolean | { closeIcon?: ReactNode; onClose?: () => void }	-	Whether the notice can be closed.
components	{ progress?: ComponentType<NotificationProgressProps> }	-	Component overrides for this notice.
description	ReactNode	-	Notice description content.
duration	number | false | null	4.5	Auto-close delay in seconds.
icon	ReactNode	-	Notice icon.
key	React.Key	-	Unique notice key. Opening with the same key updates it.
offset	number	-	Offset used by stacked positioning.
pauseOnHover	boolean	true	Pause this notice while hovering.
placement	Placement	topRight	Notice placement.
props	HTMLAttributes<HTMLDivElement> & Record<string, any>	-	Extra props passed to the notice root.
role	string	-	ARIA role for the notice.
showProgress	boolean	false	Show auto-close progress.
style	CSSProperties	-	Inline style for the notice.
styles	NotificationStyles	-	Semantic styles for notice slots.
title	ReactNode	-	Notice title content.
onClick	MouseEventHandler<HTMLDivElement>	-	Triggered when the notice is clicked.
onClose	() => void	-	Triggered when the notice closes. Prefer closable.onClose.
onMouseEnter	MouseEventHandler<HTMLDivElement>	-	Triggered when mouse enters the notice.
onMouseLeave	MouseEventHandler<HTMLDivElement>	-	Triggered when mouse leaves the notice.

Types

type Placement = 'top' | 'topLeft' | 'topRight' | 'bottom' | 'bottomLeft' | 'bottomRight';

interface StackConfig {
  threshold?: number;
  offset?: number;
}

Development

npm install
npm start
npm test
npm run tsc
npm run coverage
npm run compile
npm run build

The dumi site runs at http://localhost:8000 by default.

Release

npm run prepublishOnly

The release flow is handled by @rc-component/np through the rc-np command after the package build.

License

@rc-component/notification is released under the MIT license.