use-mailchimp-form - v3.2.1

use-mailchimp-form

A React hooks-based solution for integrating MailChimp subscribe forms into your React applications. This package handles all the business logic, allowing you to focus on the UI implementation. The view component can be fully customized or implemented with any React form library.

Features

🎣 React Hooks-based implementation
🎨 Fully customizable UI
📦 Zero dependencies (except React)
🔒 Type-safe with TypeScript support
🚀 Modern ESM and CommonJS support

Requirements

Node.js >= 22.0.0
npm >= 10.0.0
React >= 18.2.0

Installation

Using npm:

npm install use-mailchimp-form

Using yarn:

yarn add use-mailchimp-form

Setup

Getting Your Mailchimp Form Endpoint

Navigate to the Audience page in your Mailchimp dashboard
Click the dropdown menu Manage Audience > Signup Forms
Select Embedded Form

In the generated code, locate the form's action URL. It will look like:

https://aaaaaaaaa.us20.list-manage.com/subscribe/post?u=xxxxxxxxxxxxxxxxxx&id=yyyyyyyyyy

Usage

Basic Example

import { useFormFields, useMailChimpForm } from "use-mailchimp-form";

export default function SubscribeForm() {
  const url = "YOUR_SUBSCRIBE_URL";
  const { loading, error, success, message, handleSubmit } =
    useMailChimpForm(url);
  const { fields, handleFieldChange } = useFormFields({
    EMAIL: "",
  });

  return (
    <div>
      <form
        onSubmit={event => {
          event.preventDefault();
          handleSubmit(fields);
        }}
      >
        <input
          id="EMAIL"
          autoFocus
          type="email"
          value={fields.EMAIL}
          onChange={handleFieldChange}
          placeholder="Enter your email"
        />
        <button type="submit" disabled={loading}>
          {loading ? "Subscribing..." : "Subscribe"}
        </button>
      </form>

      {loading && <p>Submitting...</p>}
      {error && <p className="error">{message}</p>}
      {success && <p className="success">{message}</p>}
    </div>
  );
}

Hook Return Values

useMailChimpForm

loading: Boolean indicating submission status
error: Boolean indicating if an error occurred
success: Boolean indicating successful submission
message: String containing response message
handleSubmit: Function to handle form submission

useFormFields

fields: Object containing form field values
handleFieldChange: Function to handle field changes

Custom Form Integration

The useFormFields hook is optional. You can use your preferred form management solution (Formik, React Hook Form, etc.) with useMailChimpForm:

import { useMailChimpForm } from "use-mailchimp-form";
import { useForm } from "react-hook-form";

export default function CustomForm() {
  const { handleSubmit: submitToMailchimp } = useMailChimpForm("YOUR_URL");
  const { register, handleSubmit } = useForm();

  const onSubmit = data => {
    submitToMailchimp(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("EMAIL")} type="email" required />
      <button type="submit">Subscribe</button>
    </form>
  );
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.