@waitinglist/react

React components for easy waitinglist.dev integration. Add a beautiful, customizable waiting list form to your React application in minutes.

Installation

npm install @waitinglist/react
# or
yarn add @waitinglist/react
# or
bun add @waitinglist/react
# or
pnpm add @waitinglist/react

No additional CSS imports are required - all styling is included with the components.

Quick Start

import { WaitinglistForm } from "@waitinglist/react";

function App() {
  return (
    <WaitinglistForm
      apiKey="wl_your_api_key_here"
      fields={["email", "name", "phone"]}
      onSuccess={(data) => {
        console.log("User added to waitinglist:", data);
      }}
    />
  );
}

Components

WaitinglistForm

The main form component that handles everything for you.

import { WaitinglistForm } from "@waitinglist/react";

<WaitinglistForm
  apiKey="wl_your_api_key_here"
  fields={["email", "name", "phone"]}
  onSuccess={(data) => console.log("Success:", data)}
  onError={(error) => console.error("Error:", error)}
  submitButtonText="Join Our Waitinglist"
  successMessage="Thanks for joining!"
/>;

Props

| Prop | Type | Default | Description | | -------------------- | ------------------------------ | ------------------------ | ---------------------------------- | | apiKey | string | required | Your waitinglist.dev API key | | fields | string[] or FieldsConfig | ['email', 'name'] | Fields to show in the form | | layout | 'vertical' or 'horizontal' | 'vertical' | Form layout orientation | | onSuccess | (data) => void | - | Called when signup succeeds | | onError | (error) => void | - | Called when signup fails | | onSubmit | (data) => void | - | Called before API request | | submitButtonText | string | 'Join Waitinglist' | Submit button text | | loadingText | string | 'Joining...' | Loading state text | | successMessage | string | 'Successfully joined!' | Success message | | errorMessage | string | 'Something went wrong' | Error message | | showMessages | boolean | true | Show success/error messages | | resetOnSuccess | boolean | true | Reset form after success | | disabled | boolean | false | Disable the entire form | | tags | string[] | [] | Tags to add to signups | | className | string | - | CSS class for form element | | style | object | - | Inline styles for form element | | containerClassName | string | - | CSS class for fields container | | containerStyle | object | - | Inline styles for fields container |

Advanced Field Configuration

You can configure individual fields with detailed options and pass any props that the individual field components accept:

<WaitinglistForm
  apiKey="wl_your_api_key_here"
  layout="horizontal"
  fields={{
    email: {
      label: "Work Email",
      placeholder: "[email protected]",
      required: true,
      className: "custom-email-field",
      style: { borderRadius: "8px", fontSize: "1.1rem" },
    },
    name: {
      label: "Full Name",
      placeholder: "Enter your full name",
      required: false,
      style: { marginBottom: "1.5rem" },
    },
    phone: {
      label: "Phone Number",
      placeholder: "+1 (555) 123-4567",
      defaultCountry: "US",
      showFlag: true,
      showCountrySelect: true,
      allowCountryChange: true,
      className: "phone-input",
      style: { borderColor: "#3b82f6" },
    },
  }}
  containerClassName="fields-container"
  containerStyle={{ gap: "2rem", padding: "1rem" }}
  className="waitinglist-form"
  style={{ maxWidth: "800px", margin: "0 auto" }}
/>

Field Props Override: You can pass any prop that the individual field components (EmailField, NameField, PhoneField) accept through the fields configuration. This includes:

• className and style for custom styling
• placeholder for custom placeholders
• Phone-specific props like defaultCountry, showFlag, showCountrySelect, allowCountryChange
• Any other component-specific props

Layout Options: Use the layout prop to control form orientation:

• layout="vertical" (default): Fields stack vertically
• layout="horizontal": Fields align horizontally with responsive design

Container Styling: Use containerClassName and containerStyle to style the fields container separately from the form element.

Individual Field Components

For custom layouts, use individual field components:

import { EmailField, NameField, PhoneField } from "@waitinglist/react";

function CustomForm() {
  const [email, setEmail] = useState("");
  const [name, setName] = useState("");
  const [phone, setPhone] = useState("");

  return (
    <div>
      <EmailField
        value={email}
        onChange={setEmail}
        config={{
          label: "Your Email",
          placeholder: "[email protected]",
          required: true,
        }}
      />
      <NameField
        value={name}
        onChange={setName}
        config={{
          label: "Your Name",
          placeholder: "John Doe",
        }}
      />
      <PhoneField
        value={phone}
        onChange={setPhone}
        config={{
          label: "Phone Number",
          defaultCountry: "US",
          showFlag: true,
        }}
      />
    </div>
  );
}

API Functions

signupToWaitinglist

For complete custom implementations:

import { signupToWaitinglist } from "@waitinglist/react";

const handleSignup = async () => {
  try {
    const result = await signupToWaitinglist("wl_your_api_key", {
      email: "[email protected]",
      name: "John Doe",
      phone: "+1234567890",
      tags: ["early-access"],
    });

    console.log("Position in queue:", result.data.position);
  } catch (error) {
    console.error("Signup failed:", error);
  }
};

WaitinglistApi Class

For advanced usage with custom configuration:

import { WaitinglistApi } from "@waitinglist/react";

const api = new WaitinglistApi("wl_your_api_key", {
  apiUrl: "https://your-custom-api.com",
  timeout: 5000,
  retries: 3,
});

// Use the API instance
const result = await api.signup({ email: "[email protected]" });
const projectInfo = await api.getProjectInfo();

TypeScript Support

Full TypeScript support is included with comprehensive type definitions:

import type {
  WaitinglistFormProps,
  WaitinglistEntry,
  WaitinglistError,
} from "@waitinglist/react";
import { WaitinglistForm } from "@waitinglist/react";

const MyForm: React.FC<WaitinglistFormProps> = (props) => {
  const handleSuccess = (data: WaitinglistEntry) => {
    console.log(`Welcome! You're #${data.position} in line.`);
  };

  const handleError = (error: WaitinglistError) => {
    console.error("Signup failed:", error.message);
  };

  return (
    <WaitinglistForm
      {...props}
      onSuccess={handleSuccess}
      onError={handleError}
    />
  );
};

Styling

The components come with sensible default styles but are fully customizable:

CSS Classes

/* Target the form container */
.my-waitinglist-form {
  max-width: 500px;
  margin: 0 auto;
}

/* Target individual fields */
.my-waitinglist-form input {
  border: 2px solid #e5e7eb;
  border-radius: 8px;
}

/* Target the submit button */
.my-waitinglist-form button {
  background: linear-gradient(45deg, #3b82f6, #8b5cf6);
}

Inline Styles

import { WaitinglistForm } from "@waitinglist/react";

<WaitinglistForm
  apiKey="wl_your_api_key"
  style={{
    maxWidth: "600px",
    margin: "0 auto",
    padding: "2rem",
    backgroundColor: "#f9fafb",
    borderRadius: "1rem",
  }}
  submitButtonProps={{
    style: {
      background: "linear-gradient(45deg, #3b82f6, #8b5cf6)",
      border: "none",
      padding: "1rem",
    },
  }}
/>;

Examples

Basic Integration

import { WaitinglistForm } from "@waitinglist/react";

export default function LandingPage() {
  return (
    <div className="hero-section">
      <h1>Coming Soon!</h1>
      <p>Be the first to know when we launch.</p>

      <WaitinglistForm
        apiKey="wl_your_api_key_here"
        fields={["email", "name"]}
        successMessage="Thanks! We'll notify you when we launch."
        style={{ maxWidth: "400px", margin: "2rem auto" }}
      />
    </div>
  );
}

Advanced Custom Form

import { useState } from "react";
import {
  EmailField,
  NameField,
  PhoneField,
  signupToWaitinglist,
} from "@waitinglist/react";

export default function CustomSignup() {
  const [formData, setFormData] = useState({ email: "", name: "", phone: "" });
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);

    try {
      await signupToWaitinglist("wl_your_api_key", formData);
      alert("Success!");
    } catch (error) {
      alert("Error: " + error.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <EmailField
        value={formData.email}
        onChange={(email) => setFormData((prev) => ({ ...prev, email }))}
        config={{ label: "Work Email", required: true }}
      />

      <NameField
        value={formData.name}
        onChange={(name) => setFormData((prev) => ({ ...prev, name }))}
        config={{ label: "Full Name" }}
      />

      <PhoneField
        value={formData.phone}
        onChange={(phone) => setFormData((prev) => ({ ...prev, phone }))}
        config={{ label: "Phone Number", defaultCountry: "US" }}
      />

      <button type="submit" disabled={loading}>
        {loading ? "Joining..." : "Join Waitinglist"}
      </button>
    </form>
  );
}

Error Handling

The package provides comprehensive error handling:

import { WaitinglistForm } from "@waitinglist/react";

<WaitinglistForm
  apiKey="wl_your_api_key"
  onError={(error) => {
    // Log to your error tracking service
    console.error("Waitinglist signup failed:", error);

    // Show user-friendly message
    if (error.details) {
      error.details.forEach((detail) => {
        console.log(`${detail.field}: ${detail.message}`);
      });
    }
  }}
/>;

Examples

Interactive examples are available in the examples/ directory. To run them:

# Run interactive examples
bun run examples

# Or manually:
cd examples
bun install
bun run dev

The examples include:

• Basic Usage: Simple forms with minimal configuration
• Advanced Configuration: Custom field settings, phone input, validation
• Individual Components: Using field components separately
• API Integration: Direct API usage examples
• Custom Styling: CSS and styling examples

Development

# Install dependencies
bun install

# Build the package
bun run build

# Run examples
bun run examples

# Type checking
bun run type-check

# Linting
bun run lint

License

MIT © waitinglist.dev