Getting started

Lightweight, customizable survey widgets to collect user feedback in React apps.

Introduction

react-feedback-surveys is a standalone, open-source (MIT) UI library: no backend, no hosting, no account required. Render the components, wire onScoreSubmit/onFeedbackSubmit to your own backend (or nowhere at all).

Want AI-generated insights, a hosted dashboard, and response storage without building your own backend? Check out feedback.tools, built by the same team.

Features

• A single Survey component: the format (methodology, scale length, visual style) is configuration, not a different import
• Ready-to-use survey formats: CSAT (2 or 5 points), CES (7 points), NPS (0–10), and general text feedback
• Multiple scale styles: emoji, stars, numbers, thumbs
• Flexible placement: embed inline or display as popup overlay
• Follow-up feedback: optional text input or multiple choice responses
• Optional email collection: close the loop by capturing a respondent's email when no user identity is known
• Optional screenshot attachments: let respondents attach a screenshot, captured by a function you provide
• Built-in themes: light, dark, and auto (follows the system color scheme)
• Deep visual customization: colors, shapes, fonts, and every single part restyle from your CSS: variables, class names, and ::part() always win over the defaults. See over a dozen ready-made looks in the style catalog
• Zero dependencies
• TypeScript support

Installation

1. Install

npm i react-feedback-surveys
# or
yarn add react-feedback-surveys

2. Styles

import 'react-feedback-surveys/index.css';

Requirements

• React 18 or 19.
• Browsers: Chrome and Edge 111+, Firefox 120+, Safari 16.4+ (iOS 16.4+).
• ES modules only. The package has no CommonJS build, so require('react-feedback-surveys') doesn't work.

Next.js and Server Rendering

The components use React hooks, and the package has no 'use client' directive. In the Next.js App Router, render a survey from a Client Component:

'use client';

import { Survey } from 'react-feedback-surveys';
import 'react-feedback-surveys/index.css';

export function FeedbackSurvey() {
  return (
    <Survey
      type="nps"
      scaleStyle="numbers"
      question="How likely are you to recommend us?"
      thankYouMessage="Thanks for your feedback!"
      onScoreSubmit={({ value }) => {/* ... */}}
    />
  );
}

A Client Component is also required because the event handlers are functions, and a Server Component can't pass functions as props. Server rendering itself works: theme="auto" is pure CSS, so the page shows no flash of the wrong theme.

Quick Start

import { Survey } from 'react-feedback-surveys';
import 'react-feedback-surveys/index.css';

<Survey
  type="csat"
  points={5}
  scaleStyle="stars"
  question="How would you rate your satisfaction?"
  thankYouMessage="Thanks for your feedback!"
  onScoreSubmit={({ value }) => {/* send the rating to your backend */}}
/>

This renders an inline five-star survey. To show it in a corner of the screen, wrap it in Popup. To ask a follow-up question after the rating, add responseType (see Feedback Step).

Survey Types

One Survey component covers every format. type picks the methodology, points the scale length (CSAT only), and scaleStyle the look of the scale:

• type is required.
• points is required for type="csat" and not used for other types.
• scaleStyle is required for every type except general.
• type="general" has no rating step, only the feedback step. See General.
• value is the score that onScoreSubmit and onFeedbackSubmit receive.

TypeScript rejects invalid combinations, such as type="ces" with scaleStyle="stars".

Demo

• Live demo: View Storybook
• Style catalog: ready-made looks with CSS to copy
• Run locally: npm run storybook