> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Components

> Add gamification to React apps with EngageFabric React SDK. Use hooks and components for player profiles, quest progress, and leaderboards.

The EngageFabric React library provides pre-built, customizable components for common gamification UI patterns.

## Installation

<Note>
  The EngageFabric React components are currently available for enterprise customers and early access partners.
  Contact us at [support@engagefabric.com](mailto:support@engagefabric.com) to get access.
</Note>

Once you have access, install via npm:

```bash theme={null}
npm install @engagefabricsdk/sdk @engagefabricsdk/react
```

## Setup

Wrap your app with the EngageFabric provider:

```jsx theme={null}
import { EngageFabricProvider } from '@engagefabricsdk/react';

function App() {
  return (
    <EngageFabricProvider
      apiKey="your-api-key"
      projectId="your-project-id"
    >
      <YourApp />
    </EngageFabricProvider>
  );
}
```

***

## Components

### PlayerHeader

Display player's level, XP, and currencies:

```jsx theme={null}
import { PlayerHeader } from '@engagefabricsdk/react';

function Profile() {
  return (
    <PlayerHeader
      playerId="player-123"
      showLevel={true}
      showXP={true}
      showCurrencies={['coins', 'gems']}
    />
  );
}
```

**Props:**

| Prop             | Type       | Default  | Description             |
| ---------------- | ---------- | -------- | ----------------------- |
| `playerId`       | `string`   | required | Player ID to display    |
| `showLevel`      | `boolean`  | `true`   | Show level badge        |
| `showXP`         | `boolean`  | `true`   | Show XP progress bar    |
| `showCurrencies` | `string[]` | `[]`     | Currency IDs to display |
| `className`      | `string`   | -        | Additional CSS classes  |

***

### QuestList

Display a list of quests with progress:

```jsx theme={null}
import { QuestList } from '@engagefabricsdk/react';

function Quests() {
  return (
    <QuestList
      playerId="player-123"
      filter="active" // 'all' | 'active' | 'completed'
      onQuestClick={(quest) => console.log('Clicked:', quest)}
    />
  );
}
```

**Props:**

| Prop           | Type       | Default    | Description            |
| -------------- | ---------- | ---------- | ---------------------- |
| `playerId`     | `string`   | required   | Player ID              |
| `filter`       | `string`   | `'active'` | Filter quests          |
| `onQuestClick` | `function` | -          | Click handler          |
| `emptyMessage` | `string`   | -          | Message when no quests |

***

### AdventureOverview

Display adventure/season information:

```jsx theme={null}
import { AdventureOverview } from '@engagefabricsdk/react';

function Season() {
  return (
    <AdventureOverview
      adventureId="summer-event"
      playerId="player-123"
      showProgress={true}
      showRewards={true}
    />
  );
}
```

***

### Leaderboard

Display rankings:

```jsx theme={null}
import { Leaderboard } from '@engagefabricsdk/react';

function Rankings() {
  return (
    <Leaderboard
      leaderboardId="weekly-xp"
      limit={10}
      highlightPlayerId="player-123"
      showRankChange={true}
    />
  );
}
```

**Props:**

| Prop                | Type      | Default  | Description           |
| ------------------- | --------- | -------- | --------------------- |
| `leaderboardId`     | `string`  | required | Leaderboard ID        |
| `limit`             | `number`  | `10`     | Number of entries     |
| `highlightPlayerId` | `string`  | -        | Highlight this player |
| `showRankChange`    | `boolean` | `false`  | Show rank changes     |

***

### Lobby

Multiplayer lobby component:

```jsx theme={null}
import { Lobby } from '@engagefabricsdk/react';

function GameLobby() {
  return (
    <Lobby
      lobbyId="lobby-abc"
      playerId="player-123"
      onStart={(lobby) => startGame(lobby)}
      onLeave={() => navigate('/home')}
    />
  );
}
```

***

### Chat

Real-time chat component:

```jsx theme={null}
import { Chat } from '@engagefabricsdk/react';

function LobbyChat() {
  return (
    <Chat
      channelId="lobby-abc-chat"
      playerId="player-123"
      maxMessages={100}
      showTimestamps={true}
    />
  );
}
```

***

## Hooks

### usePlayer

```jsx theme={null}
import { usePlayer } from '@engagefabricsdk/react';

function PlayerStats() {
  const { player, loading, error, refetch } = usePlayer('player-123');

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return (
    <div>
      <h1>{player.displayName}</h1>
      <p>Level {player.level}</p>
      <p>{player.xp} XP</p>
    </div>
  );
}
```

### useQuests

```jsx theme={null}
import { useQuests } from '@engagefabricsdk/react';

function QuestPage() {
  const { quests, loading } = useQuests('player-123');

  return (
    <ul>
      {quests.map(quest => (
        <li key={quest.id}>
          {quest.name}: {quest.progress}/{quest.target}
        </li>
      ))}
    </ul>
  );
}
```

### useLeaderboard

```jsx theme={null}
import { useLeaderboard } from '@engagefabricsdk/react';

function Rankings() {
  const { rankings, loading } = useLeaderboard('weekly-xp', { limit: 10 });

  return (
    <ol>
      {rankings.map(entry => (
        <li key={entry.playerId}>
          {entry.displayName}: {entry.score}
        </li>
      ))}
    </ol>
  );
}
```

### useRealtime

```jsx theme={null}
import { useRealtime } from '@engagefabricsdk/react';

function LiveUpdates() {
  const { connected } = useRealtime('player-123', {
    onXPUpdated: (data) => toast(`+${data.amount} XP!`),
    onLevelUp: (data) => showLevelUpModal(data.newLevel),
    onQuestCompleted: (data) => showReward(data.rewards)
  });

  return <div>Status: {connected ? 'Live' : 'Connecting...'}</div>;
}
```

***

## Theming

Customize component styles:

```jsx theme={null}
import { EngageFabricProvider, createTheme } from '@engagefabricsdk/react';

const theme = createTheme({
  colors: {
    primary: '#6366F1',
    secondary: '#8B5CF6',
    success: '#10B981',
    warning: '#F59E0B',
    error: '#EF4444',
    background: '#FFFFFF',
    text: '#1F2937'
  },
  borderRadius: '8px',
  fontFamily: 'Inter, sans-serif'
});

function App() {
  return (
    <EngageFabricProvider theme={theme} ...>
      <YourApp />
    </EngageFabricProvider>
  );
}
```

***

## CSS Variables

Override styles with CSS variables:

```css theme={null}
:root {
  --ef-primary: #6366F1;
  --ef-secondary: #8B5CF6;
  --ef-border-radius: 8px;
  --ef-font-family: 'Inter', sans-serif;
}
```

***

## Other Frameworks

For non-React frameworks (Vue, Angular, Svelte), use the [JavaScript SDK](/sdks/javascript) directly or integrate via the REST API. See the [SDK Overview](/sdks/overview) for all integration options including Python, Ruby, PHP, and cURL examples.