use-easy-google-form

Use your own React form UI and let Google Forms quietly handle the collection work behind the scenes.

use-easy-google-form is a lightweight React hook that maps fields from your custom form to a Google Form and submits them for you. In short: you keep the nice frontend, Google keeps the spreadsheet, and nobody has to wrestle with the default Google Form styling unless they want to.

Why use it?

• Keep your own branded or custom React form UI.
• Submit responses directly to Google Forms without building a backend.
• Store data in the Google Forms / Google Sheets workflow you already know.
• Set it up with one hook, one formRef, and a simple field mapping.

Requirements

Runtime requirements

• react >= 16
• react-dom >= 16
• A browser environment with fetch
• An existing Google Form with the fields already created
• A Google Form that is public and accepting responses (not restricted by sign-in or organization-only access)

Local development requirements

• node >= 20
• npm >= 9 or pnpm

Currently unsupported Google Form question types: File upload, Grid, and Scale.

Installation

pnpm add @webadeva/use-easy-google-form

Or with npm:

npm install @webadeva/use-easy-google-form

Or with Yarn:

yarn add @webadeva/use-easy-google-form

Quick start

import { useRef } from "react";
import useEasyGoogleForm from "@webadeva/use-easy-google-form";

export function ContactForm() {
  const formRef = useRef<HTMLFormElement>(null);

  const onSubmit = useEasyGoogleForm({
    gFormId: "1FAIpQLSdYourGoogleFormIdHere",
    formRef,
    links: [
      { entryId: "entry.111111111", formId: "name", type: "text" },
      { entryId: "entry.222222222", formId: "message", type: "textarea" },
      { entryId: "entry.333333333", formId: "topic", type: "dropdown" },
    ],
    onSubmitExtra: () => {
      alert("Submitted. Google is now doing the paperwork.");
    },
  });

  return (
    <form ref={formRef} onSubmit={onSubmit}>
      <input id="name" placeholder="Your name" />
      <textarea id="message" placeholder="Your message" />
      <select id="topic" defaultValue="General">
        <option value="General">General</option>
        <option value="Support">Support</option>
      </select>
      <button type="submit">Send</button>
    </form>
  );
}

API

useEasyGoogleForm(params)

Returns an onSubmit handler you can pass directly to your <form> element.

Parameters

| Name | Type | Required | Description | | --------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------- | | gFormId | string | Yes | The Google Form ID from the form URL. | | formRef | RefObject<HTMLFormElement> | Yes | A React ref pointing to your form element. | | links | Array<{ entryId, formId, type }> | Yes | Maps your form fields to Google Form entries. | | extraEntries | Array<{ entryId, value }> | No | Adds extra fixed values that are not directly present in your form UI. | | onSubmitExtra | SubmitEventHandler<HTMLElement> | No | Runs after the hook finishes its submit logic. |

links object shape

Each item in links must include:

• entryId: the Google Form field name, usually something like entry.123456789
• formId: the id of the element in your own form
• type: one of the supported input types:
  • text
  • textarea
  • radio
  • checkbox
  • date
  • dropdown
  • time

Field mapping reference

| Type | Target element in your form | How the hook reads the value | | ---------- | ------------------------------------------ | -------------------------------------------------------------------- | | text | input | Reads #yourId.value | | textarea | textarea | Reads #yourId.value | | radio | Container element (div, section, etc.) | Finds input:checked inside the container | | checkbox | Container element (div, section, etc.) | Finds all input:checked inside the container | | dropdown | select | Reads select#yourId.value | | date | Container element | Looks for child inputs named day, month, and optional year | | time | Container element | Looks for child inputs named hour, minute, and optional second |

Special notes for date and time

For date fields, the inputs inside the container should use the following name attributes:

• day
• month
• year (optional if your Google Form does not need it)

For time fields, use:

• hour
• minute
• second (optional, mainly for duration-style inputs)

How to connect your Google Form

Recommended first: if you want less inspecting, less copy-pasting, and fewer "where did this entryId come from?" moments, try the companion browser extension: useEasyGoogleForm extension

It can generate a React form component from your Google Form page and makes setup much faster.

If you want to wire things up manually, here is the usual process:

1. Create your Google Form and add the questions you need.

2. Open the form menu and choose Get pre-filled link.

3. Inspect the generated page and find the input name values that look like entry.123456789.

4. Copy your Google Form ID from the URL:

   https://docs.google.com/forms/d/<gFormId>/viewform

5. Map each Google entryId to the matching element id in your React form.

If you want a helpful visual reference for the pre-filled-link approach, this article is still handy: Let’s auto fill Google Forms with URL parameters.

Tips and troubleshooting

• If submissions are not showing up, double-check that your entryId values are correct.
• Make sure the target Google Form is public and currently accepting responses. If it is locked behind sign-in or restricted to a private organization, this library will not be able to submit to it.
• For radio and checkbox, make sure the checked inputs live inside the container with the matching formId.
• For date and time, verify the child inputs use the exact required name attributes.
• If you are debugging, start with one field first, confirm it works, then add the rest. Future-you will be grateful.

Development

pnpm install
pnpm build
pnpm lint

License

MIT