# @rc-component/notification

> notification ui component for react

Latest version **2.0.8** (published 2026-08-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @rc-component/notification
pnpm add @rc-component/notification
yarn add @rc-component/notification
bun add @rc-component/notification
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.8 |
| Published | 2026-08-27 |
| First published | 2025-03-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=8.x |
| Dependencies | 3 |
| Unpacked size | 135 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 384 |
| Maintainers | zombiej, afc163, madccc, peachscript, chenshuai2144 |
| Keywords | react, react-component, react-notification, notification |

## Links

- npm: https://www.npmjs.com/package/@rc-component/notification
- Repository: https://github.com/react-component/notification
- Homepage: https://react-component.github.io/notification
- Issues: https://github.com/react-component/notification/issues
- npm.io page: https://npm.io/package/@rc-component/notification

## Dependencies (3)

- [clsx](https://npm.io/package/clsx.md) ^2.1.1
- [@rc-component/util](https://npm.io/package/@rc-component/util.md) ^1.11.0
- [@rc-component/motion](https://npm.io/package/@rc-component/motion.md) ^1.1.4

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.0.8 (latest) — 2026-08-27
- 2.0.7 — 2026-05-15
- 2.0.6 — 2026-05-07
- 2.0.5 — 2026-05-06
- 2.0.4 — 2026-05-06
- 2.0.3 — 2026-04-30
- 2.0.2 — 2026-04-28
- 2.0.1 — 2026-04-27
- 2.0.0 — 2026-04-27
- 1.2.0 — 2025-11-03
- 1.1.0 — 2025-08-05
- 1.0.2 — 2025-04-03
- 1.0.0 — 2025-03-21

## README

<div align="center">
  <h1>@rc-component/notification</h1>
  <p><sub><a href="https://ant.design"><img alt="Ant Design" height="14" src="https://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg" style="vertical-align: -0.125em;" /></a> Part of the Ant Design ecosystem.</sub></p>
  <p>🔔 Hook-based React notification primitives for stacked, animated, and accessible notices.</p>

  <p>
    <a href="https://npmjs.org/package/@rc-component/notification"><img alt="NPM version" src="https://img.shields.io/npm/v/@rc-component/notification.svg?style=flat-square"></a>
    <a href="https://npmjs.org/package/@rc-component/notification"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@rc-component/notification.svg?style=flat-square"></a>
    <a href="https://github.com/react-component/notification/actions/workflows/react-component-ci.yml"><img alt="build status" src="https://github.com/react-component/notification/actions/workflows/react-component-ci.yml/badge.svg"></a>
    <a href="https://app.codecov.io/gh/react-component/notification"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/react-component/notification/master.svg?style=flat-square"></a>
    <a href="https://bundlephobia.com/package/@rc-component/notification"><img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/@rc-component/notification?style=flat-square"></a>
    <a href="https://github.com/umijs/dumi"><img alt="dumi" src="https://img.shields.io/badge/docs%20by-dumi-blue?style=flat-square"></a>
  </p>
</div>

<p align="center">English | <a href="./README.zh-CN.md">简体中文</a></p>

## 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

```bash
npm install @rc-component/notification
```

## Usage

```tsx | pure
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>
    </>
  );
};
```

```tsx | pure
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:

```bash
npm install
npm start
```

Then open `http://localhost:8000`.

## API

### useNotification

```ts
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

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

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

## Development

```bash
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

```bash
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) license.

---
_Source: https://npm.io/package/@rc-component/notification · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._