> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.poool.fr/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Integrating Engage in React/Next

Poool Engage can be easily integrated into a React application using the dedicated library `@poool/react-engage`.
This integration allows you to display Engage elements directly inside a SPA while keeping a centralized configuration managed through the Dashboard.
Official documentation: [https://www.poool.dev/fr/docs/engage/react](https://www.poool.dev/fr/docs/engage/react)

## How it works

The integration is based on a main component, `EngageContext`, which initializes the Engage SDK and shares the configuration across the entire application.
Elements can then be displayed in two ways:
* manual rendering using `Element`
* automatic rendering using `Elements`

## Installation

```
yarn add @poool/react-engage
```

## Initialization
The first step is to wrap your application with `EngageContext`.
```
import { EngageContext } from '@poool/react-engage';

function App() {
  return (
    <EngageContext appId="YOUR_APP_ID">
      <Page />
    </EngageContext>
  );
}
```

This component initializes Engage and makes the global configuration available to all child components.

## Displaying a specific element

The `Element` component allows you to display a specific Engage element using its slug.

```
import { Element } from '@poool/react-engage';

<Element slug="element_slug" />
```

This approach is useful when you need precise control over where and how an element is rendered in your interface.

## Automatic element rendering

The `Elements` component loads and displays all elements configured in your Dashboard automatically.

```
import { Elements } from '@poool/react-engage';

<Elements />
```

Once added to your application, it retrieves and renders elements that match the rules defined in the Engage Dashboard.

## Filtering displayed elements

The `Elements` component also supports filters, allowing you to control which elements should be displayed in a given context.
This is done using the `filters` prop.

```
<Elements
	filters={['homepage', 'premium']}
/>
```

## Event handling

Engage events are also available in the React integration.
They allow you to react to user interactions (display, clicks, form submissions, etc.) and use them in your application logic.
Engage automatically triggers events during the lifecycle of elements.
In React, these events can be defined via the `events` prop, either globally in `EngageContext`, or locally on an `Element` or `Elements`.

```
<EngageContext
  appId="YOUR_APP_ID"
  events={{
    onClick: (event) => {},
    onFormSubmit: (event) => {},
  }}
>
  <App />
</EngageContext>

<Element
  slug="element_slug"
  events={{
    onClick: (event) => {},
  }}
/>
```

The received events include data that can be used to adapt behavior based on user interactions.

## Best practices
For an optimal integration:
* place `EngageContext` at the root of your application
* use `Elements` for automatic element management
* use `Element` for highly specific cases
* use `filters` to adapt display based on page or context