Skip to main content

Feedback Widget Installation

The Almirant Feedback Widget allows users of your application to send feedback directly to your project. Feedback arrives as items on Almirant's idea board, where you can triage, prioritize, and convert them into work items.

There are two ways to install it: with a script tag (for any website) or with the React/Next.js package.

Script tag (HTML)​

The simplest approach. Works on any website regardless of the framework.

1. Get your public key​

  1. Go to Settings > Integrations > Feedback Widget in your Almirant project
  2. Copy the public key (pk_...)

2. Add the script​

Add these lines before the closing </body> tag in your HTML:

<script src="https://cdn.almirant.ai/feedback-widget.iife.js"></script>
<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    position: 'bottom-right',
    theme: 'auto',
  });
</script>

That's it. A floating button will appear in the bottom-right corner of your site. Clicking it opens a form to submit feedback.

Full HTML example​

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Application</title>
</head>
<body>
  <h1>Welcome to my application</h1>

  <!-- Almirant Feedback Widget -->
  <script src="https://cdn.almirant.ai/feedback-widget.iife.js"></script>
  <script>
    FeedbackWidget.init({
      publicKey: 'pk_your_public_key',
      position: 'bottom-right',
      theme: 'auto',
    });
  </script>
</body>
</html>

React / Next.js​

If your application uses React or Next.js, you can use the official package which includes a component and a hook.

1. Install the package​

bun add @almirant/feedback-react

Or with npm:

npm install @almirant/feedback-react

2. Use the component​

import { FeedbackWidget } from '@almirant/feedback-react';

export default function App() {
  return (
    <>
      <main>
        <h1>My application</h1>
      </main>

      <FeedbackWidget
        publicKey="pk_your_public_key"
        position="bottom-right"
        theme="auto"
      />
    </>
  );
}

Usage in Next.js App Router​

In Next.js with App Router, place the widget in your root layout so it is available on all pages:

// app/layout.tsx
import { FeedbackWidget } from '@almirant/feedback-react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <FeedbackWidget
          publicKey="pk_your_public_key"
          position="bottom-right"
          theme="auto"
        />
      </body>
    </html>
  );
}
Note

The FeedbackWidget component renders only on the client. There is no need to use 'use client' in the layout; the component handles it internally.

Usage in Next.js Pages Router​

// pages/_app.tsx
import { FeedbackWidget } from '@almirant/feedback-react';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <FeedbackWidget
        publicKey="pk_your_public_key"
        position="bottom-right"
        theme="auto"
      />
    </>
  );
}

Configuration options​

Both the script tag and the React component accept the same options:

OptionTypeDefaultDescription
publicKeystring-- (required)Your project's public key (pk_...)
positionstring'bottom-right'Button position: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
themestring'auto'Visual theme: 'light', 'dark', 'auto' (detects system preference)
Tip

Use theme: 'auto' so the widget automatically adapts to the user's light/dark mode browser preference. If your application has its own theme toggle, you can pass 'light' or 'dark' dynamically.

For advanced visual customization options, see the Customization page.