@ttoss/react-notifications

About

This module provides a simple way to show notifications in your application using ttoss ecosystem.

Installation

pnpm add @ttoss/notifications @ttoss/components @ttoss/react-icons @ttoss/ui @emotion/react

Getting Started

Provider

Add a provider on top of your application and set Modal app element.

import { NotificationsProvider } from '@ttoss/react-notifications';
import { ThemeProvider } from '@ttoss/ui';
import { Modal } from '@ttoss/components';

ReactDOM.render(
  <React.StrictMode>
    <ThemeProvider>
      <NotificationsProvider>
        <App />
      </NotificationsProvider>
    </ThemeProvider>
  </React.StrictMode>,
  document.getElementById('root')
);

Modal.setAppElement('#root');

Loading

This modules provides a global loading bar that you can use on every part of your App.

import { useNotifications } from '@ttoss/react-notifications';
import { Box, Button } from '@ttoss/ui';

const Component = () => {
  const { isLoading, setLoading } = useNotifications();

  return (
    <Box>
      <Button onClick={() => setLoading(true)} disabled={isLoading}>
        Click Me!
      </Button>
    </Box>
  );
};

Modal

Set viewType to modal to show a modal notification.

import { useNotifications } from '@ttoss/react-notifications';
import { Box, Button } from '@ttoss/ui';

const Component = () => {
  const { addNotification } = useNotifications();

  return (
    <Box>
      <Button
        onClick={() =>
          addNotification({
            message: "I'm a notification",
            type: 'info',
            viewType: 'modal',
          })
        }
      >
        Click Me!
      </Button>
    </Box>
  );
};

Toast

Set viewType to toast to show a toast notification.

import { useNotifications } from '@ttoss/react-notifications';
import { Box, Button } from '@ttoss/ui';

const Component = () => {
  const { addNotification } = useNotifications();

  return (
    <Box>
      <Button
        onClick={() =>
          addNotification({
            message: "I'm a notification",
            type: 'info',
            viewType: 'toast',
          })
        }
      >
        Click Me!
      </Button>
    </Box>
  );
};

NotificationsBox

NotificationsBox displays notifications in a specific area of your application. It filters and shows only notifications intended for box display.

Basic Usage

import { NotificationsBox } from '@ttoss/react-notifications';
import { Box } from '@ttoss/ui';

const Component = () => {
  return (
    <Box>
      <NotificationsBox />
    </Box>
  );
};

Multiple Boxes

You can render multiple NotificationsBox components. By default, all boxes show the same notifications:

const App = () => {
  return (
    <Box>
      <NotificationsBox />
      <Component />
    </Box>
  );
};

Both NotificationsBox instances will display the same notifications.

Box IDs

To show notifications in a specific box, use the id prop and set the boxId in the notification:

import { useNotifications, NotificationsBox } from '@ttoss/react-notifications';
import { Box, Button } from '@ttoss/ui';

const Component = () => {
  const { addNotification } = useNotifications();

  return (
    <Box>
      <NotificationsBox id="my-box" />
      <Button
        onClick={() =>
          addNotification({
            message: "I'm a notification for my-box",
            type: 'info',
            boxId: 'my-box',
          })
        }
      >
        Click Me!
      </Button>
    </Box>
  );
};

Filtering Behavior

NotificationsBox filters notifications based on these rules:

1. View Type: Only shows notifications with viewType: 'box' or when defaultViewType is 'box' and no viewType is specified
2. Box ID:
   • If the box has no id, it shows notifications without a boxId
   • If the box has an id, it only shows notifications with a matching boxId
3. Direct Notifications: You can pass notifications directly via the notifications prop to bypass the global state

Direct Notifications

You can pass notifications directly to a specific box, bypassing the global notification state:

import { NotificationsBox } from '@ttoss/react-notifications';

const Component = () => {
  const localNotifications = [
    { id: 1, message: 'Local notification', type: 'info' },
    { id: 2, message: 'Another local one', type: 'success' },
  ];

  return <NotificationsBox notifications={localNotifications} />;
};

Props

| Prop | Type | Description | | --------------- | ------------------ | ---------------------------------------------------------------------------- | | id | string \| number | Optional identifier for the box. Used to match with boxId in notifications | | notifications | Notification[] | Optional array of notifications to display directly, bypassing global state |

NotificationsHeader

You can use NotificationsHeader to display notifications with viewType: 'header' in a specific place, such as your application's header. Only notifications with viewType: 'header' will be shown by this component.

import {
  NotificationsHeader,
  useNotifications,
} from '@ttoss/react-notifications';
import { Box, Button } from '@ttoss/ui';

const Header = () => {
  const { addNotification } = useNotifications();

  return (
    <Box>
      <NotificationsHeader />
      <Button
        onClick={() =>
          addNotification({
            message: "I'm a header notification",
            type: 'info',
            viewType: 'header',
          })
        }
      >
        Show Header Notification
      </Button>
    </Box>
  );
};

Persistent Notifications

You can create persistent notifications that will not be removed when clearNotifications() is called by setting the persist property to true. This is useful for important notifications that should remain visible until manually dismissed.

import { useNotifications } from '@ttoss/react-notifications';
import { Box, Button } from '@ttoss/ui';

const Component = () => {
  const { addNotification, clearNotifications } = useNotifications();

  return (
    <Box>
      <Button
        onClick={() =>
          addNotification({
            message: "I'm a persistent notification",
            type: 'warning',
            persist: true, // This notification will not be cleared by clearNotifications()
          })
        }
      >
        Add Persistent Notification
      </Button>
      <Button
        onClick={() =>
          addNotification({
            message: "I'm a regular notification",
            type: 'info',
            persist: false, // This notification will be cleared by clearNotifications()
          })
        }
      >
        Add Regular Notification
      </Button>
      <Button onClick={clearNotifications}>
        Clear All Non-Persistent Notifications
      </Button>
    </Box>
  );
};

Recommendation

"You can place the NotificationsBox component at the root of your application to handle notifications rendering automatically, eliminating the need to manage it manually elsewhere. If you need a specific NotificationsBox, simply render the NotificationsBox in the desired location and use the boxId property to differentiate it."

API

Notification Properties

| Property | Type | Default | Description | | ---------- | --------------------------------------------- | -------------- | ----------------------------------------------------------------------------- | | id | string \| number | Auto-generated | Unique identifier for the notification | | title | string | - | Optional title for the notification | | message | string | Required | The notification message content | | type | 'warning' \| 'error' \| 'info' \| 'success' | Required | The type of notification | | viewType | 'toast' \| 'modal' \| 'box' \| 'header' | 'box' | Where the notification should be displayed | | toast | ToastOptions | - | Additional options for toast notifications | | boxId | string \| number | - | ID of the specific NotificationsBox to display the notification | | persist | boolean | false | Whether the notification should persist when clearNotifications() is called |

useNotifications Hook

The useNotifications hook returns an object with the following properties:

| Property | Type | Description | | -------------------- | -------------------------------------------------------- | -------------------------------------------------- | | notifications | Notification[] | Array of current notifications | | addNotification | (notification: Notification \| Notification[]) => void | Function to add one or more notifications | | removeNotification | (id: string \| number) => void | Function to remove a specific notification by ID | | clearNotifications | () => void | Function to clear all non-persistent notifications | | isLoading | boolean | Current loading state | | setLoading | (loading: boolean) => void | Function to set the loading state | | defaultViewType | 'toast' \| 'modal' \| 'box' \| 'header' | The default view type for notifications |

License

MIT