useNotifications

Access and manage user notifications with support for pagination and bulk operations.

useNotifications

The useNotifications hook provides access to user notifications with support for pagination, marking as read/unread, starring, and archiving.

Return Value

loading · boolean

Whether notifications are loading

notifications · Notification[]

List of notifications

hasMore · boolean

Whether there are more notifications to load

error · Error | null

Any error that occurred

refetch

Show Refetch the notifications list

returns · Promise<void>

Resolves when the notifications list is refetched

loadMore

Show Load more notifications

returns · Promise<void>

Resolves when more notifications are loaded

markAsRead

Show Mark a notification as read

notificationId · string

The ID of the notification to mark as read

returns · Promise<void>

Resolves when the notification is marked as read

markAsUnread

Show Mark a notification as unread

notificationId · string

The ID of the notification to mark as unread

returns · Promise<void>

Resolves when the notification is marked as unread

markAllAsRead

Show Mark all notifications as read

returns · Promise<void>

Resolves when all notifications are marked as read

archiveAllRead

Show Archive all read notifications

returns · Promise<void>

Resolves when all read notifications are archived

archiveNotification

Show Archive a notification

notificationId · string

The ID of the notification to archive

returns · Promise<void>

Resolves when the notification is archived

starNotification

Show Star a notification

notificationId · string

The ID of the notification to star

returns · Promise<void>

Resolves when the notification is starred

import { useNotifications } from "@wacht/react-router";

function NotificationsPage() {
  const { notifications, loading, markAsRead, markAllAsRead, loadMore } = useNotifications();

  return (
    <div>
      <h1>Notifications</h1>
      <button onClick={() => markAllAsRead()}>Mark All Read</button>
      <ul>
        {notifications.map((notif) => (
          <li key={notif.id}>
            <span>{notif.title}</span>
            <button onClick={() => markAsRead(notif.id)}>
              Mark Read
            </button>
          </li>
        ))}
      </ul>
      <button onClick={() => loadMore()} disabled={!hasMore}>
        Load More
      </button>
    </div>
  );
}

Options

limit · number

Maximum number of notifications to fetch

scope · string

Filter notifications by scope

is_read · boolean

Filter by read status

is_archived · boolean

Filter by archived status

is_starred · boolean

Filter by starred status

severity · string

Filter by severity level

onNotification

Show Callback when a new notification is received

notification · NotificationMessage

The notification message

returns · void

No return value

Data Structures

Show Notification

interface Notification {
  id: string;
  deployment_id: string;
  user_id: string;
  organization_id?: string;
  workspace_id?: string;
  title: string;
  body: string;
  ctas?: { label: string; payload: any }[];
  severity: "info" | "success" | "warning" | "error";
  is_read: boolean;
  read_at?: string;
  is_archived: boolean;
  archived_at?: string;
  is_starred: boolean;
  metadata?: Record<string, any>;
  created_at: string;
  updated_at: string;
  expires_at?: string;
}

Examples

Basic Notifications List

import { useNotifications } from "@wacht/react-router";

function NotificationsList() {
  const { notifications, loading, markAsRead } = useNotifications();

  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {notifications.map((notif) => (
        <li key={notif.id} onClick={() => markAsRead(notif.id)}>
          {notif.title}: {notif.body}
        </li>
      ))}
    </ul>
  );
}

With Options

import { useNotifications } from "@wacht/react-router";

function UnreadOnly() {
  const { notifications } = useNotifications({
    limit: 20,
    is_read: false,
  });

  return <div>{/* Render notifications */}</div>;
}

Mark All as Read

import { useNotifications } from "@wacht/react-router";

function MarkAllButton() {
  const { markAllAsRead } = useNotifications();

  return (
    <button onClick={() => markAllAsRead()}>
      Mark All as Read
    </button>
  );
}

With Real-time Updates

import { useNotifications } from "@wacht/react-router";

function NotificationBell() {
  const { notifications, onNotification } = useNotifications({
    onNotification: (notification) => {
      toast.info(`New: ${notification.title}`);
    },
  });

  return (
    <Bell count={notifications.length} />
  );
}

Related

• useNotificationStream - Real-time notification stream