@istebit/easyforms-react

v1.0.7

Published

a month ago

Embeddable form player React component for EasyForms

0High
0Medium
0Low

istebits01

easyforms forms survey react embed

@istebit/easyforms-react

Embeddable, fully customizable React form player for EasyForms. Features complete style isolation, responsive multi-page layouts, conditional logic, file uploads, Google OAuth sign-in verification, and zero style bleed into host applications.

Installation

# npm
npm install @istebit/easyforms-core @istebit/easyforms-react

# pnpm
pnpm add @istebit/easyforms-core @istebit/easyforms-react

# yarn
yarn add @istebit/easyforms-core @istebit/easyforms-react

Quick Start

"use client";

import React from "react";
import { EasyForm } from "@istebit/easyforms-react";
import "@istebit/easyforms-react/styles.css";

export default function App() {
  return (
    <EasyForm 
      formId="your_form_id_here"
      apiKey="" //your-api-key
      endpoint="https://your-easyforms-backend.com/api"
      onSuccess={(data) => console.log("Submitted!", data)}
    />
  );
}

Props Reference

The <EasyForm /> (also exported as <FormPlayer />) component accepts the following props:

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | formId (Required) | string | — | The EasyForms form ID (MongoDB ObjectId or slug). | | apiKey | string | "" | Optional API key starting with ef_live_. | | endpoint | string | "https://api.easyforms.com" | EasyForms API base URL (e.g. http://localhost:3001/api or production URL). | | requireAuth | boolean | false | When true, requires Google One-Tap or Sign-In before responding. | | googleClientId | string | undefined | Google OAuth 2.0 Web Client ID (required when requireAuth={true}). | | showProgressBar | boolean | Form setting | Toggle progress bar visibility during multi-page or single-page navigation. | | showBranding | boolean | false | Displays the "Powered by EasyForms" footer badge. | | theme | ThemeOverrides | {} | 40+ color, typography, border, and state tokens (see Theme Customization Tokens). | | layout | FormPlayerLayout| {} | Container geometry tokens (maxWidth, padding, margin, borderRadius). | | className | string | "" | Additional CSS class for outer root wrapper. | | containerClassName | string | "" | Additional CSS class applied to the main card container (e.g. Tailwind utility classes). | | style | CSSProperties | {} | Inline CSS styles applied to the outer root wrapper. | | containerStyle | CSSProperties | {} | Inline CSS styles applied to the inner form container. | | onSuccess | (res: SubmissionResult) => void | — | Callback fired after a successful submission. | | onError | (err: Error) => void | — | Callback fired when form fetch, validation, or submission fails. | | onPageChange | (pageIndex: number) => void | — | Callback fired when navigating between multi-page sections. |

Layout & Container Customization

You can control form container dimensions and spacing via either layout props, containerClassName, or containerStyle:

<EasyForm
  formId="6a6f3afb2cb2a05f24a4e754"
  // 1. Via layout object:
  layout={{
    width: "100%",
    maxWidth: "800px",
    minWidth: "320px",
    padding: "24px",
    margin: "0 auto",
    borderRadius: "16px",
  }}
  // 2. Or via Tailwind classes:
  containerClassName="w-full max-w-3xl mx-auto p-6 md:p-8"
/>

Theme Customization Tokens

EasyForms SDK supports over 40 distinct design tokens passed through the theme prop. All tokens dynamically map to isolated CSS variables and cascade through form sub-components.

1. Global & Fonts

2. Header & Markdown Description Formatting

3. Question Cards & Labels

4. Inputs, Textareas & Selects

5. Option Cards (Radio & Checkbox)

6. File Upload Dropzones

7. Section Headers & Multi-page Dividers

8. Multi-page Step Indicators & Section Badges

9. Buttons & Progress Indicators

10. Google Sign-In Button & Verified Badge

10. Success Submission State

11. Already Responded State

12. Error States

Full Theme Configuration Example (Dark / Duotone)

Here is a full production example using high-contrast duotone styling:

import { EasyForm } from "@istebit/easyforms-react";
import "@istebit/easyforms-react/styles.css";

export function CustomForm() {
  return (
    <EasyForm
      formId="your_form_id"
      endpoint="https://api.yourdomain.com/api"
      googleClientId="YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com"
      requireAuth={true}
      showProgressBar={false}
      containerClassName="w-full max-w-4xl mx-auto p-4"
      theme={{
        primaryColor: "#ffffff",
        backgroundColor: "#000000",
        fontFamily: "Inter, sans-serif",

        headerTitleColor: "#ffffff",
        headerTitleFontSize: "2rem",
        headerDescriptionColor: "#a3a3a3",
        headerLinkColor: "#ffffff",
        markdownBoldColor: "#ffffff",
        markdownItalicColor: "#d4d4d4",
        markdownBoldItalicColor: "#ffffff",
        markdownCodeBackground: "#181818",
        markdownCodeColor: "#38bdf8",

        // Multi-page Step Indicator & Badge
        stepActiveBackground: "#171717",
        stepActiveBorderColor: "#ffffff",
        stepActiveTextColor: "#ffffff",
        stepActiveNumberBackground: "#ffffff",
        stepActiveNumberColor: "#000000",
        stepActiveRadius: "0.375rem",
        stepCompletedBackground: "#0d1f14",
        stepCompletedBorderColor: "#10b981",
        stepCompletedTextColor: "#10b981",
        stepCompletedNumberBackground: "#10b981",
        stepCompletedNumberColor: "#000000",
        stepCompletedRadius: "0.375rem",
        stepInactiveBackground: "#0d0d0d",
        stepInactiveBorderColor: "#262626",
        stepInactiveTextColor: "#737373",
        stepInactiveNumberBackground: "#262626",
        stepInactiveNumberColor: "#737373",
        stepInactiveRadius: "0.375rem",
        stepConnectorColor: "#262626",

        // Section "1 of 2" Badge Button
        stepBadgeBackground: "#141414",
        stepBadgeBorderColor: "#262626",
        stepBadgeTextColor: "#a3a3a3",
        stepBadgeCountColor: "#ffffff",
        stepBadgeRadius: "0.375rem",

        // Section Divider Header
        sectionHeaderBackground: "#0f0f0f",
        sectionHeaderBorderColor: "#262626",
        sectionHeaderTitleColor: "#ffffff",
        sectionHeaderTitleFontSize: "1.125rem",
        sectionHeaderDescriptionColor: "#a3a3a3",
        sectionHeaderDescriptionFontSize: "0.875rem",
        sectionHeaderRadius: "0.5rem",
        sectionDividerColor: "#262626",

        questionTitleColor: "#ffffff",
        questionDescriptionColor: "#888888",
        questionNumberBg: "#181818",
        questionNumberColor: "#ffffff",
        requiredAsteriskColor: "#ffffff",

        inputBackground: "#0d0d0d",
        inputTextColor: "#ffffff",
        inputBorderColor: "#262626",
        inputPlaceholderColor: "#525252",
        inputFocusBorderColor: "#ffffff",
        cardBackground: "#0a0a0a",
        cardBorderColor: "#1f1f1f",
        cardRadius: "0.75rem",

        optionBackground: "#0d0d0d",
        optionTextColor: "#ffffff",
        optionBorderColor: "#262626",
        optionHoverBackground: "#171717",
        optionHoverBorderColor: "#404040",
        optionCheckedBackground: "#1c1c1c",
        optionCheckedBorderColor: "#ffffff",
        optionCheckedTextColor: "#ffffff",

        uploadBackground: "#0d0d0d",
        uploadBorderColor: "#262626",
        uploadHoverBackground: "#171717",
        uploadHoverBorderColor: "#ffffff",
        uploadTextColor: "#a3a3a3",

        buttonBackground: "#ffffff",
        buttonTextColor: "#000000",
        buttonHoverBackground: "#e5e5e5",

        googleButtonBackground: "rgba(255, 255, 255, 0.05)",
        googleButtonBorderColor: "rgba(255, 255, 255, 0.15)",
        googleButtonHoverBackground: "rgba(255, 255, 255, 0.1)",
        googleButtonTextColor: "#ffffff",

        successCardBackground: "#0a0a0a",
        successCardBorderColor: "#262626",
        successTitleColor: "#ffffff",
        successTitleText: "Application Received!",

        alreadyRespondedCardBackground: "#0a0a0a",
        alreadyRespondedCardBorderColor: "#262626",
        alreadyRespondedTitleColor: "#ffffff",
        switchAccountButtonBackground: "#1a1a1a",
        switchAccountButtonTextColor: "#ffffff",

        errorCardBackground: "#0a0a0a",
        errorCardBorderColor: "#331111",
        errorIconColor: "#ff4444",
      }}
      onSuccess={(res) => console.log("Response ID:", res.id)}
      onError={(err) => console.error("Error:", err.message)}
    />
  );
}

Supported Question Types

The SDK renders native, responsive widgets for all 12 EasyForms question types:

short_text — Single-line input
long_text — Multi-line expanding textarea with character limits
multiple_choice — Radio option cards with instant selection
checkbox — Multi-select checkboxes
dropdown — Styled select picker
rating — Interactive 1-5 or 1-10 star rating
date — Native and custom date pickers
email — Email format validation
number — Numeric constraints and stepper
file_upload — Direct-to-storage secure file drag-and-drop
section_break — Multi-page dividers with custom titles & descriptions
multiple_choice_grid — Matrix/grid questions with criteria rows and columns

Event Handlers & Callbacks

<EasyForm
  formId="form_123"
  onPageChange={(pageIndex) => {
    console.log("User navigated to step:", pageIndex + 1);
  }}
  onSuccess={(result) => {
    console.log("Submission ID:", result.id);
    console.log("Form ID:", result.formId);
    console.log("Submitted At:", result.submittedAt);
  }}
  onError={(error) => {
    console.error("Submission failed:", error.message);
  }}
/>

Zero Style Bleed (CSS Isolation)

The SDK stylesheet @istebit/easyforms-react/styles.css is built specifically for embedded applications:

No Global Resets: Does not inject @tailwind base or preflight resets into your global <html> or <body>.
Strictly Scoped: Every CSS rule is scoped to .ezf-root, guaranteeing that host styling (e.g. Next.js, Tailwind, Chakra UI, Bootstrap) remains untouched across route transitions.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@istebit/easyforms-react

Table of Contents

Installation

Quick Start

Props Reference

Layout & Container Customization

Theme Customization Tokens

1. Global & Fonts

2. Header & Markdown Description Formatting

3. Question Cards & Labels

4. Inputs, Textareas & Selects

5. Option Cards (Radio & Checkbox)

6. File Upload Dropzones

7. Section Headers & Multi-page Dividers

8. Multi-page Step Indicators & Section Badges

9. Buttons & Progress Indicators

10. Google Sign-In Button & Verified Badge

10. Success Submission State

11. Already Responded State

12. Error States

Full Theme Configuration Example (Dark / Duotone)

Supported Question Types

Event Handlers & Callbacks

Zero Style Bleed (CSS Isolation)

License