---
title: "@playstack/audiences-react"
description: "Headless React subscription and preference-center state with explicit clients, cache boundaries, and safe errors."
tags: ["package","communication","audiences","react","nextjs","pro"]
---

{/* package-access:start */}

> **Pro.** Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/audiences-react` supplies headless state for subscribe forms and token-scoped preference centers. The package root is an explicit Client Component entry point that can sit beneath a Next.js App Router Server Component boundary.

## Install

```sh
npm install @playstack/audiences-react @playstack/audiences react
```

## Compose a subscribe form

```tsx
'use client'

import {
  createAudiencesCache,
  PlaystackAudiencesProvider,
  useAudienceSubscribe,
} from '@playstack/audiences-react'

const cache = createAudiencesCache()

function Subscribe() {
  const subscription = useAudienceSubscribe({ listKey: 'launch' })

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        void subscription.submit(
          new FormData(event.currentTarget).get('email') as string,
        )
      }}
    >
      <input name="email" type="email" />
      <button disabled={subscription.status === 'loading'}>Subscribe</button>
    </form>
  )
}

export function AudienceBoundary() {
  return (
    <PlaystackAudiencesProvider client={applicationClient} cache={cache}>
      <Subscribe />
    </PlaystackAudiencesProvider>
  )
}
```

## Provider configuration

| Property | Required | Purpose |
| --- | --- | --- |
| `client` | Yes | Application-owned subscribe and preference API client. |
| `cache` | Yes | Explicit synchronous `get`/`set`/`subscribe` boundary. |
| `toSafeError` | No | Maps application errors to approved UI copy. |
| `onError` | No | Sends the original error to caller-owned observability. |

`client.client` preserves access to the underlying HTTP or query client. The package does not install a fetch global, authentication, CAPTCHA, routing, or visual styling.

## Hooks and headless components

| API | Purpose |
| --- | --- |
| `useAudienceSubscribe({ listKey, cacheKey? })` | Submits an address, shares in-flight operations, and reports accepted or confirmation-required state. |
| `useAudiencePreferences({ token, cacheKey })` | Loads and optimistically updates token-scoped preferences. |
| `AudienceSubscribe` | Render-prop equivalent of the subscribe hook. |
| `AudiencePreferenceCenter` | Render-prop equivalent of the preferences hook. |

The preference `cacheKey` must be a stable, non-secret identifier. The signed token is intentionally never used as a cache key. Public subscribe responses containing subscriber IDs or signed tokens are rejected as invalid.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/audiences-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/audiences-react` | `./dist/index.d.ts` |
| `@playstack/audiences-react/errors` | `./dist/errors.d.ts` |
| `@playstack/audiences-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/audiences` | `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 */}