npm package: @happyreact/svelte
Description: HappyReact widget for Svelte
Author: HappyReact
Latest version: 0.1.1

# Svelte 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/svelte
```

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

```bash
yarn add @happyreact/svelte
```

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

```bash
pnpm add @happyreact/svelte
```

## 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.

---

#### SvelteKit extra setup

<Callout>
  <a href="https://kit.svelte.dev/">SvelteKit</a> is requiring extra setup to
  work. This is needed only in SvelteKit framework. The bare-bone svelte app
  doesn't need this setup.
</Callout>

1. Must exclude `@happyreact/svelte` from optimize dependencies by Vite

```ts
// vite.config.ts
const config: UserConfig = {
  [...]
  optimizeDeps: {
    exclude: ['@happyreact/svelte']
  }
};
```

2. Every page with widget must have `csr` enabled

```ts
// src/routes/+page.ts
export const csr = true;
```

Both `ssr` and `prerender` doesn't impact the work of the widget.
With the above setup, you can follow this guide.

---

### Displaying widget with basic styling

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

```svelte
<!-- FeedbackWidget.svelte -->
<script>
  import { Widget } from "@happyreact/svelte";
  import "@happyreact/svelte/theme.css";
</script>

<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.

```svelte
<!-- FeedbackWidget.svelte -->
<script>
  import { Widget } from "@happyreact/svelte";
</script>

<Widget token="[token]" resource="users-happiness" />

<style>
  :global(.hr-container) {
  }

  :global(.hr-reaction) {
  }
</style>
```

> 💡 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.

```svelte
<!-- FeedbackWidget.svelte -->
<script>
  import { Widget } from "@happyreact/svelte";
  import styles from "./FeedbackWidget.module.css";
</script>

<Widget
  token="[token]"
  resource="users-happiness"
  classes={{
    container: styles.container,
    reaction: styles.reaction,
  }}
/>
```

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

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

.container {
}

.reaction {
}
```

> 💡 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

```svelte
<!-- FeedbackWidget.svelte -->
<script>
  import { Widget } from "@happyreact/svelte";

  function handleReaction(data) {
    console.log("Reaction clicked with data", data);
  }

  function handleReactionsLimitReached() {
    console.log("Reactions limit reached");
  }
</script>

<Widget
  token="[token]"
  resource="users-happiness"
  onReaction={handleReaction}
  onReactionsLimitReached={handleReactionsLimitReached}
/>
```

> 💡 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