Pico Survey

A lightweight, flexible survey orchestration library for React applications.

Installation

npm install pico-survey
# or
yarn add pico-survey
# or
pnpm add pico-survey

Quick Start

import { PicoSurvey } from 'pico-survey';

const MySurvey = () => (
  <PicoSurvey
    config={{
      id: 'my-survey',
      pages: [<MyQuestion key="q1" id="q1" title="What's your name?" />],
    }}
    onComplete={(responses) => console.log('Done!', responses)}
  />
);

Package Scripts

Build & Development

• yarn build - Build the library (runs type-check first)
• yarn dev - Watch mode for library development
• yarn build:example - Build the example app
• yarn dev:example - Start example development server
• yarn preview:example - Preview built example app

Testing

• yarn test - Run library tests once
• yarn test:watch - Run library tests in watch mode
• yarn test:example - Run example app tests
• yarn test:example:watch - Run example app tests in watch mode
• yarn test:all - Run both library and example tests

Type Checking

• yarn type-check - Type check the library
• yarn type-check:example - Type check the example app

Code Quality

• yarn format - Format code with Biome
• yarn format:check - Check code formatting
• yarn lint - Lint code with Biome
• yarn lint:fix - Fix linting issues
• yarn check - Format and lint (with fixes)
• yarn check:ci - Format and lint check (CI mode)

Validation

• yarn validate - Type check + code quality check (CI mode)
• yarn validate:fix - Type check + code quality check (with fixes)

Analysis

• yarn analyze - Full bundle analysis (build + size report)
• yarn analyze:size - Show detailed bundle size report in terminal

Example App Scripts

The example/ directory contains a complete working implementation. Scripts:

• yarn dev - Start development server
• yarn build - Build for production
• yarn preview - Preview production build
• yarn test - Run tests
• yarn test:watch - Run tests in watch mode
• yarn type-check - Type check
• yarn type-check:watch - Type check in watch mode
• yarn type-check:strict - Type check with strict mode
• yarn lint - Lint code
• yarn lint:fix - Fix linting issues
• yarn format - Format code
• yarn format:check - Check formatting
• yarn check - Type check + lint + format check
• yarn check:fix - Fix linting and formatting

What's Included

• Survey state management with Zustand
• Navigation and branching logic
• Progress tracking utilities
• TypeScript definitions
• No UI components - you build your own

Features

• Lightweight (core library under 5KB gzipped)
• Flexible question components
• Conditional branching based on responses
• Automatic localStorage persistence
• Section-based progress tracking
• Resume from last question
• Mobile-first optimized

Philosophy

This library handles state, navigation, branching, and persistence. You handle UI, styling, and question components. This separation gives you complete control over the user experience.

Example Implementation

See example/ directory for a complete working survey with:

• Question components (SingleSelect, MultiSelect, Interstitial)
• UI components (SurveyContainer, ProgressBar)
• Survey configurations
• CSS Modules styling
• Comprehensive tests

Run it: cd example && yarn dev

License

MIT