@h2games/feedback

A lightweight Lit web component for collecting user feedback (bug reports & suggestions) and delivering them to a Lark/Feishu group chat via Custom Bot Webhook.

The widget renders as a corner drawer. A small arrow tab (the "ear") is always visible at the window edge — click it to slide the panel open, click again to close. The ear and panel slide as one unit so the ear always tracks the panel edge.

Live Demo

Installation

npm install @h2games/feedback

Peer dependencies: lit ^3.3.2 is required. react ^18 || ^19 is optional (only needed if using the React wrapper).

Quick Start

1. Next.js

Web components require client-side rendering. Create a wrapper component:

// components/feedback-widget-wrapper.tsx
"use client";

import dynamic from "next/dynamic";

const FeedbackWidget = dynamic(
  () =>
    import("@h2games/feedback/react").then((mod) => ({
      default: mod.FeedbackWidget,
    })),
  { ssr: false },
);

export const FeedbackWidgetWrapper = (
  props: React.ComponentProps<typeof FeedbackWidget>,
) => {
  return <FeedbackWidget {...props} />;
};

Then use it in your layout:

// app/layout.tsx
import { FeedbackWidgetWrapper } from "@/components/feedback-widget-wrapper";

export default function Layout({ children }) {
  return (
    <>
      {children}
      <FeedbackWidgetWrapper
        webhookUrl="https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID"
        appName="My App"
        position="bottom-right"
      />
    </>
  );
}

2. Vite + React

import { FeedbackWidget } from "@h2games/feedback/react";

export default function App() {
  return (
    <FeedbackWidget
      webhookUrl="https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID"
      appName="My App"
      position="bottom-right"
    />
  );
}

3. Vanilla JS / Any Framework

<script type="module">
  import { FeedbackWidget } from "@h2games/feedback";

  FeedbackWidget.configure({
    webhookUrl: "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID",
    appName: "My App",
    position: "bottom-right",
  });
</script>

<feedback-widget></feedback-widget>

Props / Config

| Property | Type | Required | Default | Description | | ------------ | -------------------------------------------------------------- | -------- | ---------------- | ------------------------------------- | | webhookUrl | string | Yes | — | Feishu Custom Bot webhook URL | | secret | string | No | — | Signing secret (if signature enabled) | | appName | string | No | document.title | App name shown in the Feishu message | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | No | 'bottom-right' | Corner the drawer is anchored to | | labels | FeedbackLabels | No | zh-CN defaults | Panel copy, toasts, and inline validation (see Customising Labels) |

Legacy aliases 'right' and 'left' are still accepted and map to 'bottom-right' and 'bottom-left' respectively.

Position behaviour

| Value | Drawer slides | Ear side | | -------------------------- | ------------------------------------ | -------------------- | | bottom-right (default) | in/out from the right | left edge of drawer | | bottom-left | in/out from the left | right edge of drawer | | top-right | in/out from the right (top-anchored) | left edge of drawer | | top-left | in/out from the left (top-anchored) | right edge of drawer |

Customising Labels

All visible strings in the panel (titles, field labels, placeholders, buttons), toast copy after submit, and inline validation text under fields can be overridden via the labels option. Pass the same object from FeedbackWidget.configure({ … }) or from the React wrapper’s labels prop.

successMessage and errorMessage are shown in the toast. The four *Message keys at the bottom of the table below control inline errors (shown when the user submits or blurs invalid input).

FeedbackLabels keys

| Key | Purpose | | --- | --- | | panelTitle | Panel header | | typeBug | Label for the bug-report option | | typeSuggestion | Label for the suggestion option | | typeLabel | Legend above the type control | | nameLabel | Name field label | | namePlaceholder | Name input placeholder | | emailLabel | Email field label | | emailOptional | Suffix next to the email label (e.g. “(optional)”) | | emailPlaceholder | Email input placeholder | | descriptionLabel | Description field label | | descriptionPlaceholder | Description textarea placeholder | | cancelBtn | Cancel button | | submitBtn | Submit button | | submittingBtn | Submit button label while the request is in flight | | successMessage | Toast after a successful send | | errorMessage | Toast on network / server failure, or missing webhookUrl | | nameRequiredMessage | Inline: empty name | | emailInvalidMessage | Inline: email present but invalid | | descriptionRequiredMessage | Inline: empty description | | descriptionMinLengthMessage | Inline: description shorter than 10 characters |

FeedbackWidget.configure({
  webhookUrl: "https://...",
  labels: {
    panelTitle: "Send Feedback",
    typeBug: "🐛 Bug Report",
    typeSuggestion: "💡 Suggestion",
    typeLabel: "Type",
    nameLabel: "Name",
    namePlaceholder: "Your name",
    emailLabel: "Email",
    emailOptional: "(optional)",
    emailPlaceholder: "[email protected]",
    descriptionLabel: "Description",
    descriptionPlaceholder: "Describe the issue or suggestion…",
    cancelBtn: "Cancel",
    submitBtn: "Submit",
    submittingBtn: "Sending…",
    successMessage: "Feedback sent successfully!",
    errorMessage: "Failed to send feedback, please try again.",
    nameRequiredMessage: "Please enter your name.",
    emailInvalidMessage: "Please enter a valid email address.",
    descriptionRequiredMessage: "Please enter a description.",
    descriptionMinLengthMessage: "Description must be at least 10 characters.",
  },
});

All keys are optional — any key you omit falls back to the built-in Chinese (zh-CN) default.

CSS Custom Properties

Override these on the feedback-widget element to customise appearance:

feedback-widget {
  /* Colors */
  --fb-primary: #3370ff;
  --fb-primary-hover: #2860e0;
  --fb-primary-muted: rgba(51, 112, 255, 0.08);
  --fb-danger: #f54a45;
  --fb-success: #34c724;

  /* Layout */
  --fb-radius: 8px;
  --fb-radius-sm: 2px;
  --fb-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
  --fb-panel-width: 360px;
  --fb-ear-width: 28px;

  /* Motion */
  --fb-ease: cubic-bezier(0.4, 0, 0.2, 1);
}

Webhook Setup

1. Open a Feishu/Lark group chat
2. Go to Settings > Bots > Add Bot > Custom Bot
3. Copy the Webhook URL — this is your webhookUrl
4. (Optional) Enable Signature Verification and copy the secret — this is your secret

Form Fields

The widget collects:

• Type — Bug Report or Suggestion
• Name — required
• Email — optional
• Description — required (10+ characters)
• Page URL — captured automatically

Changelog

2.1.0

• Fix: clear the toast auto-dismiss timer on disconnectedCallback so it can't fire after the widget is removed (e.g. SPA route changes)
• New CSS custom properties consumers can override: --fb-primary-muted, --fb-radius-sm, --fb-panel-width, --fb-ear-width, --fb-ease
• Internal refactor: the panel, button, toast, and widget now share a single set of design tokens defined in shared-styles.ts instead of hardcoded literals
• New named exports: isRightCorner, isTopCorner, FEEDBACK_WIDGET_TAG, plus the ToastType and FeedbackLabels types
• services/feishu-webhook.ts now uses a typed FeishuWebhookResponse for the response body

2.0.1

• README: full FeedbackLabels key reference (panel UI, toasts, and inline validation messages)

2.0.0

• Redesigned as a corner drawer with a persistent arrow-tab pinned to the viewport edge
• Four-corner positioning: 'bottom-right' (default), 'bottom-left', 'top-right', 'top-left'
• Ear and panel slide as one unit — ear stays flush to the window edge when collapsed, slides out with the panel when expanded
• Added labels option for full UI string customisation / i18n, including four keys for inline validation: nameRequiredMessage, emailInvalidMessage, descriptionRequiredMessage, descriptionMinLengthMessage
• Removed position offset CSS custom properties (--fb-offset-x, --fb-offset-y)

1.0.2

• Added link to the demo

1.0.0

• Initial release
• Feedback widget with bug report & suggestion types
• Lark/Feishu webhook integration with optional HMAC-SHA256 signing
• React wrapper component
• CSS custom properties for theming

License

MIT