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

# Embeddable Widget

> Embed Suggix directly into your website or web app to collect feedback, display roadmaps, and publish changelogs in-app.

The Suggix Embeddable Widget allows your users to explore feature requests, vote on ideas, submit new feedback, and read product release notes without ever leaving your website or application.

The widget runs in a lightweight, responsive container with smooth transitions, unread notification badges, and automatic brand color synchronization.

***

## Key Features

* **Three Embedded Modules**:
  * **Feedback**: Search, filter by board, view details, and upvote existing requests.
  * **Create**: Submit new feature requests and bug reports directly in-app.
  * **Changelog**: Discover recent release notes and product updates with unread badges.
* **Floating Launcher Button**: Elegant circular button with smooth 90-degree icon morph transitions on open and close.
* **Scroll Awareness**: Automatically slides out of the way when users scroll down, and slides back in when users scroll up (`autoHideOnScroll`).
* **Seamless Single Sign-On (SSO)**: Automatically associate votes and posts with your authenticated users using JWT tokens.
* **Custom Triggers**: Hide the default launcher and trigger the widget using any custom button, menu item, or link in your product.

***

## Installation

Choose the installation method that fits your tech stack:

> [tab] HTML Script Tag
>
> The fastest way to add Suggix to Webflow, WordPress, Shopify, Framer, or any HTML website. Paste this snippet before the closing `</body>` tag:
>
> ```html theme={null}
> <!-- Suggix Embeddable Widget -->
> <script
>   src="https://unpkg.com/suggix-widget@latest/dist/widget.js"
>   data-workspace="YOUR_WORKSPACE_SLUG"
>   data-position="bottom-right"
>   data-default-tab="feedback"
>   defer
> ></script>
> ```
>
> > [!TIP]
> >
> > Replace `YOUR_WORKSPACE_SLUG` with your Suggix workspace domain name (e.g. `acme`). You can find this in your [**Dashboard → Settings → Widgets**](https://app.suggix.com/_/settings/widgets).

> [tab] NPM Package (React / Next.js)
>
> Install the official `suggix-widget` package from npm:
>
> ```bash theme={null}
> npm install suggix-widget
> # or
> pnpm add suggix-widget
> # or
> yarn add suggix-widget
> ```
>
> Create a client-side wrapper component:
>
> ```tsx theme={null}
> 'use client';
>
> import { useEffect } from 'react';
> import { Suggix } from 'suggix-widget';
>
> export default function FeedbackWidget() {
>   useEffect(() => {
>     Suggix.init({
>       workspace: 'YOUR_WORKSPACE_SLUG',
>       position: 'bottom-right',
>       defaultTab: 'feedback',
>       autoHideOnScroll: true,
>     });
>
>     return () => {
>       Suggix.destroy();
>     };
>   }, []);
>
>   return null;
> }
> ```
>
> Mount `<FeedbackWidget />` in your root layout or application shell.

> [tab] JavaScript SDK
>
> Load the bundle and initialize programmatically with `Suggix.init()`:
>
> ```html theme={null}
> <!-- 1. Load Suggix Widget Bundle -->
> <script src="https://unpkg.com/suggix-widget@latest/dist/widget.js"></script>
>
> <!-- 2. Initialize with Configuration -->
> <script>
>   Suggix.init({
>     workspace: 'YOUR_WORKSPACE_SLUG',
>     position: 'bottom-right',
>     defaultTab: 'feedback',
>     autoHideOnScroll: true,
>   });
> </script>
> ```

***

## Configuration Options

When initializing the widget via `Suggix.init(config)` or HTML data attributes, you can configure the following options:

| Property | Type | Default | Description |
| :- | :- | :- | :- |
| `workspace` | `string` | *(Required)* | Your Suggix workspace subdomain slug (e.g. `acme`). |
| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Position of the launcher button and modal popup. |
| `defaultTab` | `'feedback' \| 'create' \| 'changelog'` | `'feedback'` | Tab to display when the widget opens. |
| `hideLauncher` | `boolean` | `false` | When `true`, hides the floating circular button so you can trigger the widget with your own elements. |
| `autoHideOnScroll` | `boolean` | `true` | Hides the floating launcher when scrolling down, and reveals it when scrolling up. |
| `offset` | `{ x: number, y: number }` | `{ x: 24, y: 24 }` | Screen edge offset in pixels. |
| `zIndex` | `number` | `2147483000` | CSS `z-index` for the launcher and widget modal. |
| `user` | `{ ssoToken: string }` | `undefined` | User credentials for Single Sign-On auto-login. |

> [!NOTE]
>
> **Brand Color**: The widget automatically inherits the Brand Color set in your Suggix Workspace (**Settings → General → Brand Color**), with `#5061bb` as the default fallback. No extra color configuration is required in code.

***

## Single Sign-On (SSO)

You can automatically sign your logged-in users into the widget so they don't have to enter their email or re-authenticate when voting or posting feedback.

### 1. Initialize with SSO Token

Generate a JWT signed with your Suggix SSO Private Key on your backend server:

```typescript theme={null}
Suggix.init({
  workspace: 'YOUR_WORKSPACE_SLUG',
  position: 'bottom-right',
  user: {
    ssoToken: 'SERVER_GENERATED_JWT_TOKEN',
  },
});
```

### 2. Identify User After Login

If your user logs in after the page has already loaded (e.g. in single-page applications), call `Suggix.identify`:

```typescript theme={null}
// When your user signs in
Suggix.identify({
  ssoToken: user.ssoToken,
});

// When your user logs out
Suggix.logout();
```

> [!NOTE]
>
> To learn how to sign JWT tokens on your server using Python, Node.js, Go, or Ruby, see the [SSO Development Guide](https://help.suggix.com/development/sso.md) and [JWT Token Guide](https://help.suggix.com/development/jwt.md).

***

## Custom Trigger Buttons

If you prefer to open the widget from your own navigation bar, settings menu, or feedback button instead of the floating circular launcher:

1. Set `hideLauncher: true` in your widget configuration.
2. Add a `data-suggix-trigger` attribute to any HTML element:

```html theme={null}
<!-- Opens the widget with the default tab -->
<button data-suggix-trigger>Give Feedback</button>
```

Or trigger specific tabs directly using the JavaScript API:

```html theme={null}
<button onclick="Suggix.open('feedback')">Browse Feedback</button>
<button onclick="Suggix.open('create')">Submit Request</button>
<button onclick="Suggix.open('changelog')">What's New</button>
```

***

## JavaScript API Reference

The global `Suggix` object (or imported `Suggix` class) provides programmatic control over the widget lifecycle:

### `Suggix.init(config)`

Initializes or reconfigures the widget. Destroys any previously active instance safely before creating the new one.

```typescript theme={null}
Suggix.init(config: SuggixConfig): void;
```

### `Suggix.open(tab?)`

Opens the widget modal. Optionally pass a target tab (`'feedback'`, `'create'`, or `'changelog'`).

```typescript theme={null}
Suggix.open(tab?: 'feedback' | 'create' | 'changelog'): void;
```

### `Suggix.close()`

Closes the widget modal.

```typescript theme={null}
Suggix.close(): void;
```

### `Suggix.toggle()`

Toggles the widget modal between open and closed states.

```typescript theme={null}
Suggix.toggle(): void;
```

### `Suggix.isOpen()`

Returns whether the widget modal is currently open.

```typescript theme={null}
Suggix.isOpen(): boolean;
```

### `Suggix.switchTab(tab)`

Switches the active tab in the currently open widget.

```typescript theme={null}
Suggix.switchTab(tab: 'feedback' | 'create' | 'changelog'): void;
```

### `Suggix.identify(user)`

Authenticates the user session in the widget using a JWT SSO token.

```typescript theme={null}
Suggix.identify(user: { ssoToken: string }): void;
```

### `Suggix.logout()`

Clears the user session inside the widget.

```typescript theme={null}
Suggix.logout(): void;
```

### `Suggix.destroy()`

Completely tears down the widget: removes the modal iframe, removes the launcher button, and unregisters all global event listeners. Always call this during component unmount in single-page apps.

```typescript theme={null}
Suggix.destroy(): void;
```

***

## Customizing in Dashboard

You can configure and test your embed code with real-time preview directly in your Suggix Dashboard:

1. Navigate to **Settings → Widgets** in your workspace console.
2. Adjust your position, default tab, and brand color.
3. Click **Preview Widget Now** to test your configuration live on the page.
4. Copy the auto-generated code snippet ready for production deployment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.