React

Install#

npm install @swingback/react

It works with React 18.2 and 19, and with server rendering: nothing reaches the page before your app runs in the browser.

Add the provider#

Put SwingbackProvider around your app, with your portal's address and the endpoint of your server that answers with the signed-in user's identity token. In Next.js's App Router, that is your root layout:

// app/layout.tsx
import { SwingbackProvider } from "@swingback/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SwingbackProvider portal="https://acme.example.com" tokenUrl="/api/feedback-token">
          {children}
        </SwingbackProvider>
      </body>
    </html>
  );
}

The endpoint answers { "token": "…" } with a token your server signs, or { "token": null } (or a 401) for nobody: Signing in your users has the function, and a widget in a Next.js app the route. It is asked each time the widget opens, with the page's cookies.

The provider puts a button at the corner of your pages, in your widget's accent color and on its side. Pass launcher={false} to leave it out and open the widget from your own buttons.

Open it from your app#

import { FeedbackButton, useSwingback } from "@swingback/react";

function Header() {
  return <FeedbackButton className="your-button">Feedback</FeedbackButton>;
}

function WhatsNew() {
  const swingback = useSwingback();
  return <button onClick={() => swingback.open("changelog")}>What's new</button>;
}

FeedbackButton is a plain <button> that opens the widget, and closes it when open. useSwingback() gives open, close, toggle, identify (call it when your user signs in or out), logout, on (the widget's events, as the JavaScript SDK's) and isOpen. A page is "feedback", "roadmap", "changelog", "new", { post: slug } or { board: slug }.

The widget in a page#

import { FeedbackWidget } from "@swingback/react";

export function Roadmap() {
  return <FeedbackWidget page="roadmap" style={{ height: 640 }} />;
}

FeedbackWidget fills its element: give it a size. Inside the provider it takes the provider's portal and token endpoint; outside one, give it portal and tokenUrl.