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