@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.

Live Demo

Installation

npm install @h2games/feedback

Peer dependencies: lit ^3.0.0 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"
      />
    </>
  );
}

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"
    />
  );
}

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",
  });
</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' | No | 'bottom-right' | Which corner the FAB appears in |

CSS Custom Properties

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

feedback-widget {
  /* Position offsets */
  --fb-offset-x: 24px;
  --fb-offset-y: 24px;

  /* Colors */
  --fb-primary: #3370ff;
  --fb-primary-hover: #2860e0;
  --fb-danger: #f54a45;
  --fb-success: #34c724;

  /* Layout */
  --fb-radius: 8px;
  --fb-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
}

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

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
• Configurable position (bottom-right / bottom-left)

License

MIT