npm package: @happyreact/react
Description: HappyReact widget for React
Author: HappyReact
Latest version: 0.2.5

# React feedback widget - Powered by Happy React

[Happy React](https://happyreact.com/) is a feedback widget for your documentation sites. Work with all documentation generators and frameworks!

This package is one of [Happy React integrations](https://happyreact.com/docs/recipes). If you want to know more please visit our [documentation page](https://happyreact.com/docs).

## Features

- Headless styling (with or without basic constraints)
- Easy integration with many frameworks
- Dashboard with statistics and extensive settings

## Installation

Using [npm](https://docs.npmjs.com/)

```bash
npm install @happyreact/react
```

Using [yarn](https://yarnpkg.com/)

```bash
yarn add @happyreact/react
```

Using [pnpm](https://pnpm.io/)

```bash
pnpm add @happyreact/react
```

## Usage

First, you need to [create a Happy React project](https://happyreact.com/docs/get-started). You will get a token to connect the widget with Happy React.
There you can change project settings, add domains to the whitelist, or see statistics.

### Displaying widget with basic styling

This code lets you add the widget to your website with the basic styling that comes with the package.

```jsx
// FeedbackWidget.jsx

import { Widget } from "@happyreact/react";
import "@happyreact/react/theme.css";

function FeedbackWidget() {
  return <Widget token="[token]" resource="users-happiness" />;
}
```

- `[token]` - project token, find it in your project settings
- `users-happiness` - unique identifier of a resource

<hr />

### Custom styles using Global CSS

Use this if your application allows importing global styles. You can use default classes to style widget elements. Please see [Happy React styling guide](https://happyreact.com/docs/styles) for more about styling.

```jsx
// FeedbackWidget.jsx

import { Widget } from "@happyreact/react";
import "./FeedbackWidget.css";

function FeedbackWidget() {
  return <Widget token="[token]" resource="users-happiness" />;
}
```

And here is our `FeedbackWidget.css` file:

```css
/* FeedbackWidget.css */

.hr-container {
}

.hr-reaction {
}
```

> 💡 Remember to replace `token` and `resource` with your project's token and proper resource

<hr />

### Custom styles using classes

Use this with Module CSS. Import styles as a variable and assign them using `classes` property.
This can let you add class to different elements of the widget. Please see [Happy React styling guide](https://happyreact.com/docs/styles) for more about styling.

```jsx
// FeedbackWidget.jsx

import { Widget } from "@happyreact/react";
import styles from "./FeedbackWidget.module.css";

const classes = {
  root: styles.root,
  container: styles.container,
};

function FeedbackWidget() {
  return (
    <Widget
      token="[token]"
      resource="users-happiness"
      classes={{
        root: styles.root,
        container: styles.container,
      }}
    />
  );
}
```

And here is our `FeedbackWidget.module.css` file:

```css
/* FeedbackWidget.module.css */

.root {
}

.container {
}
```

> 💡 Remember to replace `token` and `resource` with your project's token and proper resource

<hr />

### Reacting to user events

Right now you can use two events:

- `onReaction` - fire after user reaction
- `onReactionsLimitReached` - fire after the user reach the limit of reactions

```jsx
// FeedbackWidget.jsx

import { Widget } from "@happyreact/react";

function FeedbackWidget() {
  return (
    <Widget
      token="[token]"
      resource="users-happiness"
      onReaction={(data) => {
        console.log("Reaction clicked with data", data);
      }}
      onReactionsLimitReached={() => {
        console.log("Reactions limit reached");
      }}
    />
  );
}
```

> 💡 Remember to replace `token` and `resource` with your project's token and proper resource

<hr />

## API

The `Widget` component lets you display a feedback widget with reactions and settings.
Control these settings on [Happy React dashboard](https://app.happyreact.com).

### Required props

| Prop       | Type     | Description                          |
| :--------- | :------- | :----------------------------------- |
| `token`    | `string` | Token of your project                |
| `resource` | `string` | <br /> Unique identifier of resource |

### Optional props

| Prop                      | Default                      | Type                                                                                                                                                                                 | Description                                                                                                              |
| :------------------------ | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `classes`                 |                              | `string \| ` <br /> `{ root?: string; container?: string; grid?: string; cell?: string; reaction?: string; reactionActive?: string; reactionIcon?: string; reactionText?: string; }` | Classes applied to widget elements. You can find them on [Happy React styling guide](https://happyreact.com/docs/styles) |
| `url`                     | `https://app.happyreact.com` | `string`                                                                                                                                                                             | Url where should widget get data. Used when you have own Happy React instance                                            |
| `onReaction`              |                              | `(data: { id: string; icon: string; }) => void`                                                                                                                                      | Event fired when user click reaction                                                                                     |
| `onReactionsLimitReached` |                              | `() => void`                                                                                                                                                                         | Event fired when user reach reactions limit                                                                              |

# Learn more

You can find more integrations on [Happy React documentation](https://happyreact.com/docs).

# License

This package is licensed under MIT License