@luxoai-dev/feedback-ui · API Reference

Feedback UI.

Betav0.2.0

Two exports: a drop-in FeedbackWidget tied to a request id, and the underlying useFeedback hook for custom UIs. Both submit payloads that @luxoai-dev/agent-core/feedback validates server-side. An optional opinionated stylesheet ships under /styles.css for hosts that don’t want to design the widget from scratch.

At a glance

Package: @luxoai-dev/feedback-ui
Version: v0.2.0
Modules: . · /styles.css
Peers: react 18+ · @luxoai-dev/agent-core 0.7+
Default endpoint: POST /api/feedback

Public exports

Both exports submit to the same endpoint. The widget is the fast path; the hook lets you build a custom UI (radio dial, custom thank-you state, side-panel form, etc.).

import { FeedbackWidget, useFeedback } from "@luxoai-dev/feedback-ui";

FeedbackWidget useFeedback FeedbackWidgetProps UseFeedbackOptions UseFeedbackResult SubmitFeedbackInput

Component

FeedbackWidget

Beta

function FeedbackWidget(props: FeedbackWidgetProps): JSX.Element

Drop-in 1-5 rating form tied to a request id. Renders data-feedback-state attributes (ready / error / submitted) for styling. POSTs the submission to the configured endpoint.

Parameters

Param	Type	Required	Description
props.requestId	string	Required	The LLM call's gateway requestId. Server-side validation requires this.
props.endpoint	string	Optional	Submit URL. Defaults to '/api/feedback'.
props.fetchImpl	typeof fetch	Optional	Custom fetch (for testing or SSR).
props.onSuccess	(entry: FeedbackEntry) => void	Optional	Called after a successful submission with the validated entry returned by the server.
props.onError	(error: Error) => void	Optional	Called when validation or network fails.
props.promptLabel	string	Optional	Label above the rating row. Defaults to 'How was this answer?'.
props.thanksLabel	string	Optional	Replacement content shown after submit. Defaults to 'Thanks for the feedback.'.
props.commentPlaceholder	string	Optional	Placeholder for the optional comment textarea.
props.submitLabel	string	Optional	Submit button label. Defaults to 'Send'.
props.showComment	boolean	Optional	Show the comment textarea. Defaults to true.
props.className	string	Optional	Forwarded to the root form element.
props.style	CSSProperties	Optional	Forwarded to the root form element.

example.tsTypeScriptExample

import { FeedbackWidget } from "@luxoai-dev/feedback-ui";

export function TriageFeedback({ requestId }: { requestId: string }) {
  return (
    <FeedbackWidget
      requestId={requestId}
      promptLabel="Was this triage useful?"
      submitLabel="Submit feedback"
      onSuccess={(entry) => console.log("recorded", entry.requestId)}
      onError={(err) => console.error(err)}
    />
  );
}

Hook

useFeedback

Beta

function useFeedback(options?: UseFeedbackOptions): UseFeedbackResult

Headless hook that submits validated payloads to the feedback endpoint. Tracks submitting / submitted / error state. Use this when you need a custom UI.

Parameters

Param	Type	Required	Description
options.endpoint	string	Optional	Submit URL. Defaults to '/api/feedback'.
options.fetchImpl	typeof fetch	Optional	Custom fetch implementation.
options.onSuccess	(entry: FeedbackEntry) => void	Optional	Called with the validated entry on success.
options.onError	(error: Error) => void	Optional	Called when submission fails.

Returns

UseFeedbackResult

Object with submit(input), submitting, submitted, error, reset().

example.tsTypeScriptExample

"use client";
import { useFeedback } from "@luxoai-dev/feedback-ui";

export function CustomFeedbackBar({ requestId }: { requestId: string }) {
  const { submit, submitting, submitted, error, reset } = useFeedback();

  if (submitted) {
    return (
      <div>
        <span>Thanks!</span>
        <button onClick={reset}>Submit another</button>
      </div>
    );
  }

  return (
    <div>
      {[1, 2, 3, 4, 5].map((score) => (
        <button
          key={score}
          disabled={submitting}
          onClick={() => submit({ requestId, score: score as 1 | 2 | 3 | 4 | 5 })}
        >
          {score}★
        </button>
      ))}
      {error ? <p role="alert">{error.message}</p> : null}
    </div>
  );
}

interface

FeedbackWidgetProps

interface FeedbackWidgetProps extends UseFeedbackOptions {
  requestId: string;
  className?: string;
  style?: CSSProperties;
  promptLabel?: string;
  thanksLabel?: string;
  commentPlaceholder?: string;
  submitLabel?: string;
  showComment?: boolean;
}

Extends UseFeedbackOptions with display-only props. The widget always renders requestId, score buttons, optional comment, and a submit button — text labels are configurable, the structure is not.

interface

UseFeedbackOptions

interface UseFeedbackOptions {
  endpoint?: string;
  fetchImpl?: typeof fetch;
  onSuccess?: (entry: FeedbackEntry) => void;
  onError?: (error: Error) => void;
}

interface

UseFeedbackResult

interface UseFeedbackResult {
  submit: (input: SubmitFeedbackInput) => Promise<void>;
  submitting: boolean;
  submitted: boolean;
  error: Error | null;
  reset: () => void;
}

Fields

Field	Type	Required	Description
submit	(input) => Promise<void>	Required	Submit a feedback payload. Validation happens server-side; this resolves on success or sets error on failure.
submitting	boolean	Required	True while a request is in-flight.
submitted	boolean	Required	True after a successful submit. Stays true until reset() is called.
error	Error \| null	Required	Last error from submit(), or null.
reset	() => void	Required	Clear submitted + error so a new submission can run.

interface

SubmitFeedbackInput

interface SubmitFeedbackInput {
  requestId: string;
  score: 1 | 2 | 3 | 4 | 5;
  comment?: string;
  tags?: string[];
  metadata?: Record<string, unknown>;
}

Payload submitted to the endpoint. Mirrors the agent-core FeedbackEntry shape minus the server-set fields (userId, tenantId, createdAt — those are added on the server).

Optional stylesheet · /styles.css

Added in v0.2.0. A minimal opinionated stylesheet for FeedbackWidget — star row, comment textarea, submit button, error, and submitted states. Every element is selected by its data-feedback-* attribute so hosts can override individual rules without specificity wars. Includes a prefers-color-scheme: dark block for dark hosts that don’t pass a custom palette.

import "@luxoai-dev/feedback-ui/styles.css";

Constant

@luxoai-dev/feedback-ui/styles.css

since v0.2Beta

/* opinionated stylesheet, attribute-scoped */
[data-feedback-widget]    { /* root form */ }
[data-feedback-stars]     { /* 1-5 star row */ }
[data-feedback-star]      { /* individual star button */ }
[data-feedback-comment]   { /* optional textarea */ }
[data-feedback-submit]    { /* submit button */ }
[data-feedback-state="error"]     { /* error state */ }
[data-feedback-state="submitted"] { /* thank-you state */ }
@media (prefers-color-scheme: dark) { /* dark overrides */ }

Import once in a client component or the root layout. The widget already emits the matching data-feedback-* attributes — no additional props required. Skip this import to style the widget yourself; the component still works without it.

example.tsTypeScriptExample

// app/layout.tsx (or any client component that renders FeedbackWidget)
import "@luxoai-dev/feedback-ui/styles.css";

// Override a single rule without removing the rest:
// app/globals.css
[data-feedback-star][aria-pressed="true"] {
  color: var(--brand-yellow);
}

Public exports

Both exports submit to the same endpoint. The widget is the fast path; the hook lets you build a custom UI (radio dial, custom thank-you state, side-panel form, etc.).

import { FeedbackWidget, useFeedback } from "@luxoai-dev/feedback-ui";

FeedbackWidget useFeedback FeedbackWidgetProps UseFeedbackOptions UseFeedbackResult SubmitFeedbackInput

Component

FeedbackWidget

Beta

function FeedbackWidget(props: FeedbackWidgetProps): JSX.Element

Drop-in 1-5 rating form tied to a request id. Renders data-feedback-state attributes (ready / error / submitted) for styling. POSTs the submission to the configured endpoint.

Parameters

Param	Type	Required	Description
props.requestId	string	Required	The LLM call's gateway requestId. Server-side validation requires this.
props.endpoint	string	Optional	Submit URL. Defaults to '/api/feedback'.
props.fetchImpl	typeof fetch	Optional	Custom fetch (for testing or SSR).
props.onSuccess	(entry: FeedbackEntry) => void	Optional	Called after a successful submission with the validated entry returned by the server.
props.onError	(error: Error) => void	Optional	Called when validation or network fails.
props.promptLabel	string	Optional	Label above the rating row. Defaults to 'How was this answer?'.
props.thanksLabel	string	Optional	Replacement content shown after submit. Defaults to 'Thanks for the feedback.'.
props.commentPlaceholder	string	Optional	Placeholder for the optional comment textarea.
props.submitLabel	string	Optional	Submit button label. Defaults to 'Send'.
props.showComment	boolean	Optional	Show the comment textarea. Defaults to true.
props.className	string	Optional	Forwarded to the root form element.
props.style	CSSProperties	Optional	Forwarded to the root form element.

example.tsTypeScriptExample

import { FeedbackWidget } from "@luxoai-dev/feedback-ui";

export function TriageFeedback({ requestId }: { requestId: string }) {
  return (
    <FeedbackWidget
      requestId={requestId}
      promptLabel="Was this triage useful?"
      submitLabel="Submit feedback"
      onSuccess={(entry) => console.log("recorded", entry.requestId)}
      onError={(err) => console.error(err)}
    />
  );
}

Hook

useFeedback

Beta

function useFeedback(options?: UseFeedbackOptions): UseFeedbackResult

Headless hook that submits validated payloads to the feedback endpoint. Tracks submitting / submitted / error state. Use this when you need a custom UI.

Parameters

Param	Type	Required	Description
options.endpoint	string	Optional	Submit URL. Defaults to '/api/feedback'.
options.fetchImpl	typeof fetch	Optional	Custom fetch implementation.
options.onSuccess	(entry: FeedbackEntry) => void	Optional	Called with the validated entry on success.
options.onError	(error: Error) => void	Optional	Called when submission fails.

Returns

UseFeedbackResult

Object with submit(input), submitting, submitted, error, reset().

example.tsTypeScriptExample

"use client";
import { useFeedback } from "@luxoai-dev/feedback-ui";

export function CustomFeedbackBar({ requestId }: { requestId: string }) {
  const { submit, submitting, submitted, error, reset } = useFeedback();

  if (submitted) {
    return (
      <div>
        <span>Thanks!</span>
        <button onClick={reset}>Submit another</button>
      </div>
    );
  }

  return (
    <div>
      {[1, 2, 3, 4, 5].map((score) => (
        <button
          key={score}
          disabled={submitting}
          onClick={() => submit({ requestId, score: score as 1 | 2 | 3 | 4 | 5 })}
        >
          {score}★
        </button>
      ))}
      {error ? <p role="alert">{error.message}</p> : null}
    </div>
  );
}

interface

FeedbackWidgetProps

interface FeedbackWidgetProps extends UseFeedbackOptions {
  requestId: string;
  className?: string;
  style?: CSSProperties;
  promptLabel?: string;
  thanksLabel?: string;
  commentPlaceholder?: string;
  submitLabel?: string;
  showComment?: boolean;
}

Extends UseFeedbackOptions with display-only props. The widget always renders requestId, score buttons, optional comment, and a submit button — text labels are configurable, the structure is not.

interface

UseFeedbackOptions

interface UseFeedbackOptions {
  endpoint?: string;
  fetchImpl?: typeof fetch;
  onSuccess?: (entry: FeedbackEntry) => void;
  onError?: (error: Error) => void;
}

interface

UseFeedbackResult

interface UseFeedbackResult {
  submit: (input: SubmitFeedbackInput) => Promise<void>;
  submitting: boolean;
  submitted: boolean;
  error: Error | null;
  reset: () => void;
}

Fields

Field	Type	Required	Description
submit	(input) => Promise<void>	Required	Submit a feedback payload. Validation happens server-side; this resolves on success or sets error on failure.
submitting	boolean	Required	True while a request is in-flight.
submitted	boolean	Required	True after a successful submit. Stays true until reset() is called.
error	Error \| null	Required	Last error from submit(), or null.
reset	() => void	Required	Clear submitted + error so a new submission can run.

interface

SubmitFeedbackInput

interface SubmitFeedbackInput {
  requestId: string;
  score: 1 | 2 | 3 | 4 | 5;
  comment?: string;
  tags?: string[];
  metadata?: Record<string, unknown>;
}

Payload submitted to the endpoint. Mirrors the agent-core FeedbackEntry shape minus the server-set fields (userId, tenantId, createdAt — those are added on the server).

Optional stylesheet · /styles.css

import "@luxoai-dev/feedback-ui/styles.css";

Constant

@luxoai-dev/feedback-ui/styles.css

since v0.2Beta

/* opinionated stylesheet, attribute-scoped */
[data-feedback-widget]    { /* root form */ }
[data-feedback-stars]     { /* 1-5 star row */ }
[data-feedback-star]      { /* individual star button */ }
[data-feedback-comment]   { /* optional textarea */ }
[data-feedback-submit]    { /* submit button */ }
[data-feedback-state="error"]     { /* error state */ }
[data-feedback-state="submitted"] { /* thank-you state */ }
@media (prefers-color-scheme: dark) { /* dark overrides */ }

example.tsTypeScriptExample

// app/layout.tsx (or any client component that renders FeedbackWidget)
import "@luxoai-dev/feedback-ui/styles.css";

// Override a single rule without removing the rest:
// app/globals.css
[data-feedback-star][aria-pressed="true"] {
  color: var(--brand-yellow);
}