open-loopback

Beautiful, embeddable feedback widget for React.

open-loopback is a polished, themeable feedback component you can drop into any React app.
It supports modal and embedded layouts, emoji/star/number ratings, rich theming (including dark mode), and both controlled and uncontrolled usage.

Installation

npm install open-loopback
# or
yarn add open-loopback
# or
pnpm add open-loopback

Peer dependencies

Make sure your project has:

• react ≥ 16.8.0
• react-dom ≥ 16.8.0

Quick Start

Modal widget (uncontrolled)

import React from "react";
import { Loopback } from "open-loopback";
import "open-loopback/style.css"; // include styles

export function App() {
  return (
    <div>
      <h1>My App</h1>
      <Loopback
        sourceId="my-product"
        variant="modal"
        position="bottom-right"
        defaultOpen={false}
      />
    </div>
  );
}

Embedded widget (inline card)

import React from "react";
import { Loopback } from "open-loopback";
import "open-loopback/style.css";

export function FeedbackSection() {
  return (
    <section style={{ maxWidth: 420, margin: "0 auto", padding: 24 }}>
      <Loopback
        sourceId="docs-section"
        variant="embedded"
        ratingType="emoji"
        content={{
          title: "How helpful was this page?",
          subtitle: "Your feedback helps us improve.",
        }}
      />
    </section>
  );
}

Component Overview

The main export is:

• Loopback – the feedback UI component
• LoopbackProps – TypeScript props interface (re-exported)

You'll typically import it like:

import { Loopback } from "open-loopback";

…and once at app entry:

import "open-loopback/style.css";

Props

LoopbackProps

• sourceId (string, required)
  Unique identifier for the feedback source (e.g. "homepage-hero", "pricing-page", "docs-search").

• variant ("modal" | "embedded")

  • "modal": Floating trigger button + overlay card.
  • "embedded": Renders the card inline where you place the component.
  • Default: "modal".

• position ("bottom-right" | "bottom-left" | "center")
  Position of the modal trigger/overlay.
  Default: "bottom-right".

• ratingType ("emoji" | "star" | "number")
  How the rating scale is displayed.
  Default: "emoji".

• ratingItems (LoopbackRatingItem[])
  Custom rating items if you want your own scale.

  Each LoopbackRatingItem is:

  • value (number)
  • label (ReactNode)

  If omitted, the widget uses:

  • Emojis 😭 → 🤩 for "emoji",
  • 1–5 numeric scale for "star" / "number".

• isOpen (boolean)
  Control prop for the modal’s open state.
  When set, the component becomes controlled – you must handle open/close state yourself and respond to onClose.

• defaultOpen (boolean)
  Initial open state for uncontrolled modal usage.
  Default: false.

• onClose (() => void)
  Called when the widget should close (close button or after a successful submit).
  Use this to toggle your own isOpen state when in controlled mode.

• showTrigger (boolean)
  Show the floating trigger button for variant="modal" in uncontrolled mode.

  • Set to false if you want to render your own button and control isOpen manually.
  • Default: true.

• triggerAriaLabel (string)
  Accessible label for the trigger button.
  Default: "Open feedback".

• theme (LoopbackTheme)
  Theming options (see Theming below).

• content (LoopbackContent)
  Custom copy and labels, e.g. headings, helper text, button labels.

• metadata (Record<string, unknown>)
  Optional custom data to send along with the feedback. Automatically merged with default metadata (url, referrer).

| Prop | Type | Default | Description | | ------------------- | ------------------------- | ------- | ------------------------------------------------------- | | cardStyle | CSSProperties | - | Optional inline styles for the main widget card. | | triggerStyle | CSSProperties | - | Optional inline styles for the floating trigger button. | | submitButtonStyle | CSSProperties | - | Optional inline styles for the submit button. | | ratingButtonStyle | CSSProperties | - | Optional inline styles for the rating buttons. | | headerStyle | CSSProperties | - | Optional inline styles for the header container. | | textareaStyle | CSSProperties | - | Optional inline styles for the textarea. | | metadata | Record<string, unknown> | - | Custom data payload for submissions. |

Key Features

• Character Limit: Feedback text is capped at 1000 characters. A counter is provided to guide the user.
• Automatic Metadata: By default, the widget captures page context:
  • url (current window location)
  • referrer (originating page)
• Error Handling: Graceful error states and retry UI for failed submissions.

Theming

We use standard CSS variables for styling. You can override these in your global CSS or via the theme prop.

The library automatically derives hover colors (darkening by 10% for primary, 5% for accent) using color-mix. You can override this behavior by setting --lb-primary-hover or --lb-accent-hover explicitly.

<Loopback
  theme={{
    primaryColor: "#E11D48", // Rose-600
    backgroundColor: "#ffffff",
    textColor: "#0f172a",
    starColor: "#cbd5e1", // Optional: customize inactive star color
    starActiveColor: "#fbbf24", // Optional: customize active star color
  }}
/>

Exported Types

We export several types to help with TypeScript development:

• LoopbackProps
• LoopbackTheme
• FeedbackPosition
• FeedbackRatingType
• LoopbackRatingItem
• LoopbackContent

LoopbackTheme

• primaryColor? (string) – Accent color (buttons, active states).
• backgroundColor? (string) – Card background.
• textColor? (string) – Primary text color.
• accentColor? (string) – Subtle accent background.
• borderColor? (string) – Card + input border color.
• borderRadius? (string) – Radius for the card and elements.
• fontFamily? (string) – Custom font stack.
• darkMode? (boolean) – Opt into a dark-friendly style; fills in sensible dark defaults.
• zIndex? (number) – Stack order for modal overlay and trigger.

Example

<Loopback
  sourceId="checkout"
  variant="modal"
  position="center"
  ratingType="star"
  theme={{
    primaryColor: "#f97316",
    backgroundColor: "#020617",
    textColor: "#e5e7eb",
    darkMode: true,
    borderRadius: "16px",
    zIndex: 9999,
  }}
/>

Under the hood, the widget maps these values to CSS variables like:

• --lb-primary
• --lb-bg
• --lb-text
• --lb-border
• --lb-font-family
• --lb-z-index
• etc.

You can further customize styling in your own CSS by targeting:

• .lb-root
• .lb-widget-overlay
• .lb-widget-trigger
• .lb-widget-card
• .lb-textarea
• .lb-submit-btn
• …

Controlled vs Uncontrolled

You can let the widget manage its own open/close state or wire it to your own UI.

Uncontrolled (simplest)

<Loopback
  sourceId="homepage"
  variant="modal"
  defaultOpen={false}
  showTrigger={true}
/>

The widget:

• Draws its own trigger button.
• Handles open/close internally.

Controlled (custom trigger)

import React from "react";
import { Loopback } from "open-loopback";
import "open-loopback/style.css";

export function ControlledExample() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Give feedback</button>

      <Loopback
        sourceId="pricing"
        variant="modal"
        isOpen={open}
        onClose={() => setOpen(false)}
        showTrigger={false} // hide built-in trigger
      />
    </>
  );
}

License

MIT

You’re free to use, modify, and embed open-loopback in your own projects.