@aperovn/funnel-sdk

React component library for building conversion funnels with automatic analytics, screen-based routing, and a themable design system.

Features

• Screen-based router — declarative funnel flows with built-in transitions
• Session tracking — pluggable adapter pattern; default emits screen-view/answer/conversion events
• Design system — 40+ components (quizzes, paywalls, forms, auth, charts, animations)
• Theme tokens — colors, spacing, typography, motion, shadows, radius — runtime-swappable
• Stripe integration — Payment Element + checkout flow primitives (optional peer)
• Zero-config animations — transition presets, reduced-motion aware, gesture hooks

Install

npm install @aperovn/funnel-sdk
# or
bun add @aperovn/funnel-sdk

Peer dependencies

| Peer | Required | Notes | |------|----------|-------| | react >=18 | yes | | | react-dom >=18 | yes | | | next >=14 | yes | App Router supported | | @stripe/stripe-js ^1.54 \|\| ^2 \|\| ^3 \|\| ^4 | optional | only if using CheckoutFlow / PaymentForm | | @stripe/react-stripe-js ^2 \|\| ^3 | optional | same as above |

Quick start

import {
  FunnelProvider,
  FunnelRouter,
  ThemeProvider,
  Screen,
  Text,
  Button,
} from "@aperovn/funnel-sdk";
import "@aperovn/funnel-sdk/theme";

const screens = {
  welcome: {
    component: () => (
      <Screen>
        <Text type="heading">Welcome</Text>
        <Button action={{ type: "navigate", to: "quiz" }}>Start</Button>
      </Screen>
    ),
  },
  quiz: {
    component: () => (
      <Screen>
        <Text>Question 1...</Text>
      </Screen>
    ),
  },
};

export default function App() {
  return (
    <ThemeProvider>
      <FunnelProvider funnelSlug="my-funnel">
        <FunnelRouter screens={screens} initialScreen="welcome" />
      </FunnelProvider>
    </ThemeProvider>
  );
}

Components

Layout & containers

Screen · Rows · Columns · Carousel · Popup

Typography & media

Text · Image · Video · Chart · RawHTML

Quiz & options

Options · QuizSimple · QuizMultipleChoice · QuizEmoji · QuizImagePicker · QuizIcons · QuizCoverImages · Rating · PopupQuestion

Inputs

Input · DatePicker

Buttons & timer

Button · PulseButton · CountdownButton · OAuthButton · Timer · CheckoutButton

Auth

EmailForm · EmailOAuth · OAuthButtons

Loaders

Spinner · Loader · Processing

Paywall & checkout

PlanPickerSimple · PlanPickerComposite · TrialPricePicker · WalletButton · CookieConsent · DeeplinkHandoff · CheckoutFlow · PaymentForm

Engagement

Reviews · CustomerCarousel · FAQ

Routing

import { FunnelRouter, useRouter } from "@aperovn/funnel-sdk";

function NextButton() {
  const { goTo, current } = useRouter();
  return <button onClick={() => goTo("next-screen")}>Next</button>;
}

Flow & transition config is declarative — see FlowsConfig and TransitionsConfig types for the full surface.

Session tracking

Default adapter emits events to your analytics endpoint. Swap it via SessionProvider:

import { SessionProvider, DefaultSessionAdapter, type SessionAdapter } from "@aperovn/funnel-sdk";

const myAdapter: SessionAdapter = {
  init: async (opts) => { /* ... */ },
  track: async (event) => { /* send to your backend */ },
  end: async () => { /* ... */ },
};

<SessionProvider adapter={myAdapter}>
  {/* funnel */}
</SessionProvider>

Theme

Import the stylesheet once at app root:

import "@aperovn/funnel-sdk/theme";

Use ThemeProvider to switch schemes at runtime; tokens (colors, spacing, typography, motion, shadows, radius, zIndex) are exported for programmatic access.

import { ThemeProvider, useTheme } from "@aperovn/funnel-sdk";

function ThemeToggle() {
  const { scheme, setScheme } = useTheme();
  return <button onClick={() => setScheme(scheme === "light" ? "dark" : "light")}>Toggle</button>;
}

Animations

import { ScreenTransition, transitionPresets, useReducedMotion } from "@aperovn/funnel-sdk";

<ScreenTransition preset="slide-left" duration={300}>
  {/* screen content */}
</ScreenTransition>

Hooks: usePressAnimation, useHoverAnimation, useSwipe, useReducedMotion.

Bundle size

| Bundle | Size | |--------|------| | ESM | ~57 kB minified | | CJS | ~60 kB minified | | Theme CSS | ~26 kB | | Tokens CSS | ~6 kB |

Tree-shakeable — only imported components ship.

TypeScript

First-class TypeScript support. All component props, action types, theme tokens, and router config are typed.

License

Proprietary — © Apero Group. Contact the maintainer for licensing terms.