npm package: @notiflows/react
Description: Notiflows React SDK - components and hooks for notification UIs
Author: Notiflows
Latest version: 0.2.1

# @notiflows/react

Official React SDK for Notiflows - components and hooks for building notification UIs.

## Installation

```bash
npm install @notiflows/react
# or
pnpm add @notiflows/react
# or
yarn add @notiflows/react
```

## Quick Start

Import the styles and wrap your app with `NotiflowsProvider`:

```tsx
import '@notiflows/react/styles.css'
import { NotiflowsProvider } from '@notiflows/react'

function App() {
  return (
    <NotiflowsProvider
      apiKey="pk_your_public_key"
      userId="user_123"
      userKey="jwt_token_here"
      channelId="in_app"
    >
      <YourApp />
    </NotiflowsProvider>
  )
}
```

### Pre-built Components

Use the pre-built notification feed:

```tsx
import {
  FeedRoot,
  FeedTrigger,
  FeedContent,
  BellButton,
} from '@notiflows/react'

function NotificationBell() {
  return (
    <FeedRoot>
      <FeedTrigger>
        <BellButton />
      </FeedTrigger>
      <FeedContent />
    </FeedRoot>
  )
}
```

### Custom UI with Hooks

Build your own UI using hooks:

```tsx
import { useFeed, useNotificationStatus } from '@notiflows/react'

function CustomNotifications() {
  const { entries, isLoading, totalUnread, loadMore } = useFeed()
  const { markAsRead, markAllAsRead } = useNotificationStatus()

  if (isLoading) return <div>Loading...</div>

  return (
    <div>
      <p>Unread: {totalUnread}</p>
      <button onClick={markAllAsRead}>Mark all read</button>

      {entries.map((entry) => (
        <div key={entry.id} onClick={() => markAsRead(entry.id)}>
          {entry.data.body}
        </div>
      ))}

      <button onClick={loadMore}>Load more</button>
    </div>
  )
}
```

## Components

### Provider

- `NotiflowsProvider` - Context provider for Notiflows client

### Feed Components

- `FeedRoot` - Popover root (wraps Radix Popover)
- `FeedTrigger` - Trigger button wrapper
- `FeedContent` - Popover content with notification list
- `BellButton` - Bell icon with unread badge
- `Badge` - Unread count badge
- `Notification` - Individual notification item
- `MarkAllAsRead` - Button to mark all as read
- `MarkAsArchived` - Archive button

### Preferences

- `Preferences` - Preferences panel with channel toggles

## Hooks

### `useNotiflows()`

Access the Notiflows client and feed client:

```tsx
const { client, feedClient } = useNotiflows()
```

### `useFeed(options?)`

Manage notification feed state:

```tsx
const {
  entries,          // FeedEntry[]
  totalUnread,      // number
  totalUnseen,      // number
  isLoading,        // boolean
  isLoadingMore,    // boolean
  error,            // NotiflowsApiError | null
  loadMore,         // () => Promise<void>
  clearError,       // () => void
  retry,            // () => void
} = useFeed({
  status?: 'unseen' | 'unread' | 'read' | 'archived',
  notiflow?: string,    // filter by notiflow handle
  topic?: string,       // filter by topic
  archived?: boolean,   // include archived entries
  limit?: number,
})
```

### `useNotificationStatus()`

Update notification states:

```tsx
const {
  markAsSeen,
  markAsRead,
  markAsClicked,
  markAsArchived,
  batchMarkAsRead,
  markAllAsRead,
} = useNotificationStatus()
```

### `usePreferences()`

Manage user preferences:

```tsx
const {
  preferences,
  isLoading,
  updateNotiflowPreferences,
} = usePreferences()
```

## Styling

### Default Styles

Import the default styles for a ready-to-use UI:

```tsx
import '@notiflows/react/styles.css'
```

### Customization

Override CSS variables to match your brand:

```css
:root {
  --nf-primary: #your-brand-color;
  --nf-background: #ffffff;
  --nf-foreground: #171717;
  --nf-border: #e5e5e5;
  --nf-radius: 0.5rem;
}
```

### Dark Mode

Add the `dark` class to a parent element:

```html
<html class="dark">
```

The components will automatically use dark mode colors.

## Next.js

For Next.js App Router, use `'use client'` directive:

```tsx
'use client'

import { NotiflowsProvider } from '@notiflows/react'
```

## Documentation

Full documentation is available at [notiflows.com/docs/sdks/client-side/react](https://notiflows.com/docs/sdks/client-side/react).

## License

MIT