---
title: React helper | Featurebase
description: <FeaturebaseProvider> and useFeaturebase() for declarative usage in React apps.
---

`featurebase-js/react` is an optional helper that handles the boot / update / shutdown lifecycle for you and exposes the messenger’s reactive state via a hook.

## Install

Terminal window

```
pnpm add featurebase-js
# react is a peer dependency — already in your app
```

## `<FeaturebaseProvider>`

Wrap your app once. The Provider boots the messenger on mount, re-identifies on identity change without rebooting, and shuts down on unmount.

```
import { FeaturebaseProvider } from 'featurebase-js/react';


export function Root({ user }: { user: { id: string; email: string; hash: string } }) {
  return (
    <FeaturebaseProvider
      appId="org_your_id"
      userId={user.id}
      email={user.email}
      userHash={user.hash}
    >
      <App />
    </FeaturebaseProvider>
  );
}
```

The Provider accepts every field on `FeaturebaseSettings`. Pass them as React props.

### What it handles

- **Boot once** on mount, even under React StrictMode (boot-or-update routing).
- **Re-identify** on `userId` / `email` / `userHash` change without rebooting.
- **Shutdown** on unmount, clearing the cached identity so the next mount is a fresh boot.
- **Subscribes** to `onUnreadCountChange` so descendants can read a live count via `useFeaturebase()`.

## `useFeaturebase()`

Imperative + reactive access from any component beneath the Provider.

```
import { useFeaturebase } from 'featurebase-js/react';


export function ChatLauncher() {
  const { show, unreadCount } = useFeaturebase();
  return (
    <button onClick={show} aria-label={`Open chat, ${unreadCount} unread`}>
      Chat {unreadCount > 0 && <span className="badge">{unreadCount}</span>}
    </button>
  );
}
```

The returned object exposes:

```
{
  show, hide, showSpace, showMessages,
  showArticle, showChangelog, showNews, showConversation, showNewMessage,
  setTheme, setLanguage,
  update, shutdown,
  unreadCount,  // reactive — re-renders when it changes
}
```

Method identities are stable across renders; only `unreadCount` triggers re-renders.

## Common patterns

### Sync the launcher with your in-app theme

```
import { useEffect } from 'react';
import { useFeaturebase } from 'featurebase-js/react';


export function ThemeBridge({ theme }: { theme: 'light' | 'dark' }) {
  const { setTheme } = useFeaturebase();
  useEffect(() => {
    setTheme(theme);
  }, [theme, setTheme]);
  return null;
}
```

### Open an article from a marketing CTA

```
const { showArticle } = useFeaturebase();
return <button onClick={() => showArticle('art_intro_to_billing')}>How billing works</button>;
```

### Drop the Provider entirely

If you’d rather skip the Provider, see the [direct-import React example](/guides/featurebase-js/frameworks#react/index.md) in the frameworks guide.