---
title: "@playstack/notifications-react"
description: "Headless React state for a persisted notification inbox, unread counts, pagination, and optimistic mutations."
tags: ["package","communication","notifications","react","inbox","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/notifications-react` supplies headless React state for an authenticated in-app inbox. It does not install authentication, routes, fetch globals, realtime connections, or visual styling.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/notifications-react@0.1.0-beta.1
```

Check the peer requirements below before choosing a runtime or provider.

{/* package-install:end */}

## Compose an inbox

```tsx
'use client'

import {
  createNotificationsInboxCache,
  PlaystackNotificationsProvider,
  useNotificationsInbox,
} from '@playstack/notifications-react'

const cache = createNotificationsInboxCache()

function Inbox() {
  const inbox = useNotificationsInbox()

  return inbox.notifications.map((notification) => (
    <button
      key={notification.id}
      onClick={() => inbox.markRead(notification.id)}
    >
      {notification.title}
    </button>
  ))
}

export function InboxBoundary() {
  return (
    <PlaystackNotificationsProvider client={inboxClient} cache={cache}>
      <Inbox />
    </PlaystackNotificationsProvider>
  )
}
```

The package root is a Client Component entry point and can be mounted below a Next.js App Router Server Component boundary.

## Provider configuration

| Property | Required | Purpose |
| --- | --- | --- |
| `client` | Yes | Application-owned authenticated list, read, and archive client. |
| `cache` | Yes | Explicit external-store-compatible cache boundary. |
| `cacheKey` | No | Separates inbox state when the application has multiple subjects or roots. |
| `pageSize` | No | Number of rows requested per page. |
| `includeArchived` | No | Includes archived rows in list requests. |
| `now` | No | Application-controlled time for optimistic read state. |
| `onError` | No | Sends original client errors to caller-owned observability. |

`useNotificationsInbox()` exposes notifications, unread count, pagination state, `refresh`, `loadMore`, `markRead`, and `archive`. Mutations update optimistically and roll back on rejection; pagination de-duplicates rows by ID. `NotificationsInbox` offers the same state as a render-prop component.

`client.client` preserves the underlying HTTP or query client as the provider escape hatch.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/notifications-react@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/notifications-react` | `./dist/index.d.ts` |
| `@playstack/notifications-react/errors` | `./dist/errors.d.ts` |
| `@playstack/notifications-react/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

| Peer | Compatible range | When needed |
| --- | --- | --- |
| `@playstack/core` | `0.1.0-beta.1` | Required by the package. |
| `@playstack/notifications` | `0.1.0-beta.1` | Required by the package. |
| `react` | `^18.2.0 \|\| ^19.0.0` | Required by the package. |

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}