React hooks & components

npm install @notifykitjs/react

import { NotifyKitProvider } from "@notifykitjs/react"

<NotifyKitProvider options={{ baseUrl: "/api/notifykit" }}>
  {children}
</NotifyKitProvider>

import { useInbox } from "@notifykitjs/react"

function InboxPage() {
  const { items, markRead } = useInbox()

  return (
    <ul>
      {items.map(item => (
        <li key={item.id}>
          <strong>{item.title}</strong>
          {item.body && <p>{item.body}</p>}
          {!item.readAt && (
            <button onClick={() => markRead(item.id)}>Mark read</button>
          )}
        </li>
      ))}
    </ul>
  )
}

// Disable auto-loading (useful for conditional rendering)
const inbox = useInbox({ autoLoad: false })

// Then manually load when ready:
useEffect(() => { inbox.refresh() }, [])

function InboxWithStates() {
  const { items, status, markRead, refresh } = useInbox()

  if (status === "loading") return <Skeleton count={3} />
  if (status === "error") return (
    <div className="error">
      Failed to load notifications.
      <button onClick={refresh}>Retry</button>
    </div>
  )

  if (items.length === 0) return <p>No notifications yet.</p>

  return items.map(item => (
    <NotificationCard key={item.id} item={item} onRead={markRead} />
  ))
}

import { usePreferences } from "@notifykitjs/react"

function NotificationSettings() {
  const { isEnabled, update } = usePreferences()

  return (
    <label>
      <input
        type="checkbox"
        checked={isEnabled("comment_mentioned", "email")}
        onChange={(e) => update({
          notificationId: "comment_mentioned",
          channels: { email: e.target.checked },
        })}
      />
      Email me when someone mentions me
    </label>
  )
}

import { usePreferences } from "@notifykitjs/react"
import { createNotifyKitClient } from "@notifykitjs/react"
import { useEffect, useState } from "react"

const client = createNotifyKitClient({ baseUrl: "/api/notifykit" })

type NotificationMeta = {
  id: string
  description?: string
  category?: string
  channels: string[]
  required?: boolean
}

function NotificationPreferencesPage() {
  const { isEnabled, update, status } = usePreferences()
  const [notifications, setNotifications] = useState<NotificationMeta[]>([])

  useEffect(() => {
    client.notifications.list().then(setNotifications)
  }, [])

  if (status === "loading" || notifications.length === 0) {
    return <p>Loading preferences...</p>
  }

  // Group by category
  const grouped = Object.groupBy(notifications, n => n.category ?? "General")

  return (
    <div className="preferences-page">
      <h1>Notification settings</h1>
      <p>Choose how you want to be notified for each type of event.</p>

      {Object.entries(grouped).map(([category, items]) => (
        <section key={category}>
          <h2>{category}</h2>
          <table>
            <thead>
              <tr>
                <th>Notification</th>
                <th>Inbox</th>
                <th>Email</th>
              </tr>
            </thead>
            <tbody>
              {items?.map(n => (
                <tr key={n.id}>
                  <td>
                    <strong>{n.id.replace(/_/g, " ")}</strong>
                    {n.description && <p>{n.description}</p>}
                    {n.required && <span className="badge">Required</span>}
                  </td>
                  {["inbox", "email"].map(ch => (
                    <td key={ch}>
                      {n.channels.includes(ch) ? (
                        <input
                          type="checkbox"
                          checked={isEnabled(n.id, ch)}
                          disabled={n.required}
                          onChange={e => update({
                            notificationId: n.id,
                            channels: { [ch]: e.target.checked },
                          })}
                          aria-label={`${ch} for ${n.id.replace(/_/g, " ")}`}
                        />
                      ) : (
                        <span aria-label="Not available">—</span>
                      )}
                    </td>
                  ))}
                </tr>
              ))}
            </tbody>
          </table>
        </section>
      ))}
    </div>
  )
}

import { useUnreadCount } from "@notifykitjs/react"

function NotificationBadge() {
  const { unreadCount } = useUnreadCount({ pollInterval: 10_000 })

  if (unreadCount === 0) return null

  return (
    <span className="badge">{unreadCount > 99 ? "99+" : unreadCount}</span>
  )
}

import { NotificationBell } from "@notifykitjs/react"

// Default: renders "(3)" when 3 unread
<NotificationBell />

// Custom:
<NotificationBell render={({ unreadCount }) => (
  <div className="bell-icon">
    {unreadCount > 0 && <span className="badge">{unreadCount}</span>}
  </div>
)} />

import { Inbox } from "@notifykitjs/react"

<Inbox
  emptyState={<p>You're all caught up!</p>}
  renderItem={({ item, markRead }) => (
    <div className="notification-card">
      <h4>{item.title}</h4>
      <p>{item.body}</p>
      {item.actionUrl && <a href={item.actionUrl}>View</a>}
      {!item.readAt && (
        <button onClick={() => markRead(item.id)}>Dismiss</button>
      )}
    </div>
  )}
/>

import { createNotifyKitClient } from "@notifykitjs/react"

const client = createNotifyKitClient({ baseUrl: "/api/notifykit" })

// Inbox operations
const items = await client.inbox.list()
await client.inbox.markRead(items[0].id)
await client.inbox.markAllRead()
await client.inbox.archive(items[0].id)
await client.inbox.deleteItem(items[0].id)

// Preferences
const prefs = await client.preferences.list()
await client.preferences.update({
  notificationId: "comment_mentioned",
  channels: { email: false },
})

// Notification metadata (for building settings UIs)
const notifications = await client.notifications.list()
// [{ id: "comment_mentioned", channels: ["inbox","email"], ... }]

import { useInbox } from "@notifykitjs/react"
import { useState } from "react"

function NotificationCenter() {
  const { items, unreadCount, markRead, markAllRead } = useInbox()
  const [open, setOpen] = useState(false)

  return (
    <div className="relative">
      <button onClick={() => setOpen(!open)}>
        🔔 {unreadCount > 0 && <span className="badge">{unreadCount}</span>}
      </button>

      {open && (
        <div className="dropdown">
          <div className="header">
            <span>Notifications</span>
            {unreadCount > 0 && (
              <button onClick={markAllRead}>Mark all read</button>
            )}
          </div>
          {items.length === 0
            ? <p>You're all caught up!</p>
            : items.map(item => (
                <a
                  key={item.id}
                  href={item.actionUrl ?? "#"}
                  onClick={() => !item.readAt && markRead(item.id)}
                  className={item.readAt ? "read" : "unread"}
                >
                  <strong>{item.title}</strong>
                  {item.body && <p>{item.body}</p>}
                </a>
              ))
          }
        </div>
      )}
    </div>
  )
}

function FilteredInbox() {
  const { items, refresh } = useInbox()
  const [tab, setTab] = useState<"all" | "unread" | "archived">("all")

  const filtered = items.filter(item => {
    if (tab === "unread") return !item.readAt
    if (tab === "archived") return !!item.archivedAt
    return !item.archivedAt // "all" = non-archived
  })

  return (
    <>
      <nav className="tabs" role="tablist">
        {(["all", "unread", "archived"] as const).map(t => (
          <button
            key={t}
            role="tab"
            aria-selected={tab === t}
            onClick={() => setTab(t)}
          >
            {t === "all" ? "All" : t === "unread" ? "Unread" : "Archived"}
          </button>
        ))}
      </nav>
      {filtered.length === 0
        ? <p className="empty">No {tab} notifications</p>
        : filtered.map(item => <NotificationCard key={item.id} item={item} />)
      }
    </>
  )
}

function GroupedInbox() {
  const { items } = useInbox()

  const groups = Object.groupBy(items, item => {
    const d = new Date(item.createdAt)
    const today = new Date()
    if (d.toDateString() === today.toDateString()) return "Today"
    const yesterday = new Date(today)
    yesterday.setDate(yesterday.getDate() - 1)
    if (d.toDateString() === yesterday.toDateString()) return "Yesterday"
    return d.toLocaleDateString(undefined, { month: "short", day: "numeric" })
  })

  return (
    <>
      {Object.entries(groups).map(([label, groupItems]) => (
        <section key={label}>
          <h4 className="group-label">{label}</h4>
          {groupItems.map(item => <NotificationCard key={item.id} item={item} />)}
        </section>
      ))}
    </>
  )
}

function TypedNotificationCard({ item, markRead }: {
  item: InboxItem
  markRead: (id: string) => Promise<InboxItem>
}) {
  switch (item.notificationId) {
    case "team_invite":
      return (
        <div className="notification-card notification-card--invite">
          <strong>{item.title}</strong>
          <div className="notification-actions">
            <button onClick={() => acceptInvite(item)}>Accept</button>
            <button onClick={() => declineInvite(item)}>Decline</button>
          </div>
        </div>
      )

    case "comment_mentioned":
      return (
        <div className="notification-card notification-card--mention">
          <strong>{item.title}</strong>
          {item.body && <blockquote>{item.body}</blockquote>}
          <a href={item.actionUrl ?? "#"}>View thread</a>
        </div>
      )

    case "deploy_succeeded":
    case "deploy_failed":
      return (
        <div className="notification-card notification-card--deploy">
          <span className={item.notificationId === "deploy_succeeded" ? "badge-green" : "badge-red"}>
            {item.notificationId === "deploy_succeeded" ? "✓" : "✗"}
          </span>
          <strong>{item.title}</strong>
          {item.actionUrl && <a href={item.actionUrl}>View logs</a>}
        </div>
      )

    default:
      return (
        <div className="notification-card">
          <strong>{item.title}</strong>
          {item.body && <p>{item.body}</p>}
          {!item.readAt && (
            <button onClick={() => markRead(item.id)}>Dismiss</button>
          )}
        </div>
      )
  }
}

// Registry pattern — scales to many types without a long switch
const RENDERERS: Record<string, React.ComponentType<{ item: InboxItem }>> = {
  team_invite: InviteCard,
  comment_mentioned: MentionCard,
  deploy_succeeded: DeployCard,
  deploy_failed: DeployCard,
}

function NotificationCard({ item }: { item: InboxItem }) {
  const Renderer = RENDERERS[item.notificationId] ?? GenericCard
  return <Renderer item={item} />
}

function PaginatedInbox() {
  const { items, status } = useInbox()
  const [visibleCount, setVisibleCount] = useState(10)

  const visible = items.slice(0, visibleCount)
  const hasMore = visibleCount < items.length

  return (
    <>
      {visible.map(item => <NotificationCard key={item.id} item={item} />)}
      {hasMore && (
        <button onClick={() => setVisibleCount(c => c + 10)}>
          Load more ({items.length - visibleCount} remaining)
        </button>
      )}
    </>
  )
}

import { useInbox } from "@notifykitjs/react"
import { useEffect, useRef, useState } from "react"

function useNotificationToast() {
  const { items } = useInbox()
  const [toast, setToast] = useState<{ id: string; title: string } | null>(null)
  const prevCount = useRef(items.length)

  useEffect(() => {
    // Only trigger on new items (count increased), not on initial load
    if (items.length > prevCount.current && prevCount.current > 0) {
      const newest = items[0]
      setToast({ id: newest.id, title: newest.title })

      // Auto-dismiss after 5 seconds
      const timer = setTimeout(() => setToast(null), 5000)
      return () => clearTimeout(timer)
    }
    prevCount.current = items.length
  }, [items.length])

  return { toast, dismiss: () => setToast(null) }
}

function AppLayout({ children }: { children: React.ReactNode }) {
  const { toast, dismiss } = useNotificationToast()

  return (
    <>
      {children}
      {toast && (
        <div className="toast" role="status" aria-live="polite">
          <span>{toast.title}</span>
          <button onClick={dismiss} aria-label="Dismiss">×</button>
        </div>
      )}
    </>
  )
}

function useToastQueue(maxVisible = 3) {
  const { items } = useInbox()
  const [toasts, setToasts] = useState<Array<{ id: string; title: string }>>([])
  const prevCount = useRef(items.length)

  useEffect(() => {
    if (items.length > prevCount.current && prevCount.current > 0) {
      const newest = items[0]
      setToasts(prev => [{ id: newest.id, title: newest.title }, ...prev].slice(0, maxVisible))

      setTimeout(() => {
        setToasts(prev => prev.filter(t => t.id !== newest.id))
      }, 5000)
    }
    prevCount.current = items.length
  }, [items.length])

  return { toasts, dismiss: (id: string) => setToasts(prev => prev.filter(t => t.id !== id)) }
}

function AccessibleInbox() {
  const { items, unreadCount, markRead } = useInbox()

  return (
    <>
      <button aria-label={`Notifications, ${unreadCount} unread`}>
        🔔 {unreadCount > 0 && <span aria-hidden="true">{unreadCount}</span>}
      </button>

      <ul role="listbox" aria-label="Notifications" aria-live="polite">
        {items.map(item => (
          <li key={item.id} role="option" aria-selected={!item.readAt}>
            <a href={item.actionUrl ?? "#"}>
              <strong>{item.title}</strong>
              {item.body && <p>{item.body}</p>}
            </a>
            {!item.readAt && (
              <button
                aria-label={`Mark "${item.title}" as read`}
                onClick={() => markRead(item.id)}
              >
                Dismiss
              </button>
            )}
          </li>
        ))}
      </ul>
    </>
  )
}

import { render, screen, waitFor } from "@testing-library/react"
import userEvent from "@testing-library/user-event"
import { describe, it, expect, beforeEach } from "vitest"
import { NotifyKitProvider } from "@notifykitjs/react"
import { createNotifyKit, memoryAdapter, fakeEmailProvider, createHandler } from "@notifykitjs/core"
import { commentMentioned } from "@/lib/notifications"
import { InboxPage } from "./inbox-page" // your component

let testNotify
let handler

// 3. Wrapper that intercepts fetch and routes to the handler
function TestWrapper({ children }: { children: React.ReactNode }) {
  return (
    <NotifyKitProvider
      options={{
        baseUrl: "/api/notifykit",
        fetch: (input, init) => {
          const url = typeof input === "string"
            ? input
            : input instanceof URL
              ? input.toString()
              : input.url
          return handler(new Request(new URL(url, "http://test"), init))
        },
      }}
    >
      {children}
    </NotifyKitProvider>
  )
}

describe("InboxPage", () => {
  beforeEach(async () => {
    testNotify = createNotifyKit({
      notifications: [commentMentioned] as const,
      database: memoryAdapter(),
      providers: { email: fakeEmailProvider() },
    })
    handler = createHandler(testNotify, {
      identify: async () => ({ recipientId: "test_user" }),
    })
    await testNotify.upsertRecipient({ id: "test_user", email: "test@test.com" })
  })

  it("renders inbox items after send", async () => {
    await testNotify.send({
      recipientId: "test_user",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })

    render(<InboxPage />, { wrapper: TestWrapper })

    await waitFor(() => {
      expect(screen.getByText(/Rey mentioned you/)).toBeInTheDocument()
    })
  })

  it("marks item as read on click", async () => {
    await testNotify.send({
      recipientId: "test_user",
      notificationId: "comment_mentioned",
      payload: { actorName: "Sam", postUrl: "/p/2" },
    })

    render(<InboxPage />, { wrapper: TestWrapper })

    await waitFor(() => {
      expect(screen.getByText(/Sam mentioned you/)).toBeInTheDocument()
    })

    await userEvent.click(screen.getByRole("button", { name: /mark.*read/i }))

    await waitFor(() => {
      expect(screen.queryByRole("button", { name: /mark.*read/i })).not.toBeInTheDocument()
    })
  })

  it("shows empty state when inbox is empty", async () => {
    render(<InboxPage />, { wrapper: TestWrapper })

    await waitFor(() => {
      expect(screen.getByText(/no notifications/i)).toBeInTheDocument()
    })
  })
})

import { PreferencesPage } from "./preferences-page"

it("toggles email off for a notification", async () => {
  render(<PreferencesPage />, { wrapper: TestWrapper })

  await waitFor(() => {
    expect(screen.getByLabelText(/email.*comment/i)).toBeChecked()
  })

  await userEvent.click(screen.getByLabelText(/email.*comment/i))

  await waitFor(() => {
    expect(screen.getByLabelText(/email.*comment/i)).not.toBeChecked()
  })

  // Verify the preference persisted
  const e = await testNotify.explain({
    recipientId: "test_user",
    notificationId: "comment_mentioned",
    payload: { actorName: "Rey", postUrl: "/p/1" },
  })
  expect(e.channels.email.outcome).toBe("disabled")
})

// For testing error UI, use a mock fetch that returns an error
function ErrorWrapper({ children }: { children: React.ReactNode }) {
  return (
    <NotifyKitProvider
      options={{
        baseUrl: "/api/notifykit",
        fetch: () => Promise.resolve(Response.json(
          { error: "Unauthenticated", code: "UNAUTHENTICATED" },
          { status: 401 },
        )),
      }}
    >
      {children}
    </NotifyKitProvider>
  )
}

it("shows error state on 401", async () => {
  render(<InboxPage />, { wrapper: ErrorWrapper })

  await waitFor(() => {
    expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
    expect(screen.getByRole("button", { name: /retry/i })).toBeInTheDocument()
  })
})