@clearlaunch/feedback

Let your users raise bugs, feature requests, enhancements and feedback from inside your product. Submissions land on your ClearLaunch board as typed cards.

No dependencies, no framework, ~6kB gzipped.

Install

npm i @clearlaunch/feedback

import { mountFeedback } from '@clearlaunch/feedback';

mountFeedback({ token: 'fb_…' });   // ClearLaunch → project → Feedback

That's it — a floating button appears bottom-right, opens a dialog, and submissions arrive on your board.

Script tag, if you'd rather:

<script src="https://unpkg.com/@clearlaunch/feedback/dist/feedback.umd.js"></script>
<script>ClearLaunchFeedback.mountFeedback({ token: 'fb_…' });</script>

Triggers

Floating button (default) — a pill in a corner:

mountFeedback({
  token: 'fb_…',
  trigger: { kind: 'floating', corner: 'bottom-right', inset: 20 },
});

Sticky edge tab — clings to an edge, rotated to run along it. offset positions it along that edge and takes a number (px), a percentage, or any CSS length:

trigger: { kind: 'sticky', edge: 'right', offset: '50%' }        // centred
trigger: { kind: 'sticky', edge: 'left',  offset: 0 }            // top of the edge
trigger: { kind: 'sticky', edge: 'right', offset: 'calc(100% - 300px)' }

Your own control — render nothing and call open():

const fb = mountFeedback({ token: 'fb_…', trigger: { kind: 'none' } });

myButton.addEventListener('click', () => fb.open());
reportBugLink.addEventListener('click', () => fb.open('bug'));  // preselect a type

The dialog

• Type — Bug, Feature, Improvement, Feedback. Restrict or reorder with types: ['bug', 'feedback'].
• Summary and Details.
• Images — paste a screenshot straight into Details, or drop files on the dialog. Up to 5, 5MB each; stored in your project's bucket and attached to the card.
• Email — asked only when you haven't supplied user.email.

Theming

mountFeedback({
  token: 'fb_…',
  theme: {
    primaryColor: '#8b5cf6',
    fontFamily: 'Inter, sans-serif',
    borderRadius: '10px',
    colorScheme: 'auto',   // 'auto' follows the OS; force 'light' | 'dark'
    zIndex: 9999,          // raise if your own overlays sit above it
  },
});

Everything is namespaced under .clf- and every property is set explicitly, so the widget looks the same whatever CSS your page has.

Context and attribution

mountFeedback({
  token: 'fb_…',
  user: { email: '[email protected]', name: 'Jane' },   // skips the email field
  metadata: { plan: 'pro', tenant: 'acme', build: __BUILD_SHA__ },
  source: 'support-portal',
});

metadata is appended to the card description. source is the important one — see below.

Reading your tickets back

Every submission carries a source (default 'feedback'), copied onto the card. Query by it to show your users' tickets inside your product:

GET /api/v1/cards?projectId=…&source=support-portal
GET /api/v1/cards?projectId=…&source=support-portal&cardType=bug
GET /api/v1/cards?projectId=…&source=web,mobile&cardType=bug,enhancement

Both source and cardType accept comma-separated lists. Types map to real card types, so a "bugs only" filter works:

| Dialog | Card type | |---|---| | Bug | bug | | Feature | feature | | Improvement | enhancement | | Feedback | task |

Use distinct source values when you embed on several surfaces ('web-app', 'mobile', 'docs') so you can filter or route each one.

Where submissions land

On your board in To Do by default, so they enter the normal flow. Set a different column in ClearLaunch → project → Feedback if you'd rather triage them separately.

Bugs are raised as p1, everything else p2.

API

const fb = mountFeedback(options);

fb.open();          // open the dialog
fb.open('bug');     // open with a type preselected
fb.close();
fb.destroy();       // remove the trigger, dialog and styles

Options

| Option | Type | Default | |---|---|---| | token | string | required | | apiUrl | string | hosted ClearLaunch API | | trigger | sticky | floating | none | { kind: 'floating' } | | types | FeedbackType[] | all four | | defaultType | FeedbackType | first in types | | source | string | 'feedback' | | user | { email?, name? } | — | | metadata | Record<string,string> | — | | theme | FeedbackTheme | — | | text | Partial<FeedbackText> | English defaults | | onSubmit / onError / onOpen / onClose | callbacks | — |

Every string in the dialog can be replaced via text, so it can be localised without forking the package.

Notes

• SSR-safe. With no document it returns an inert widget, so importing it never breaks a server render.
• The token is public — it identifies your feedback form and is meant to ship in the browser. It only permits submissions, never reads.
• Submissions are rate-limited to 10/min per form.