{"id":17722888,"url":"https://github.com/enthusiastic-js/form-observer","last_synced_at":"2025-09-10T00:38:39.212Z","repository":{"id":205689014,"uuid":"593379950","full_name":"enthusiastic-js/form-observer","owner":"enthusiastic-js","description":"A simple utility for reacting to events from a form's fields","archived":false,"fork":false,"pushed_at":"2024-04-13T18:47:40.000Z","size":1306,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-14T09:05:14.458Z","etag":null,"topics":["form","html","js","lit","observer","preact","progressive-enhancement","react","solid","svelte","validation","vue","web"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/enthusiastic-js.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-01-25T21:30:37.000Z","updated_at":"2024-04-16T13:32:48.062Z","dependencies_parsed_at":"2024-01-02T02:39:17.902Z","dependency_job_id":"7b38f347-b587-4538-a2fc-1b289a4362fb","html_url":"https://github.com/enthusiastic-js/form-observer","commit_stats":{"total_commits":217,"total_committers":1,"mean_commits":217.0,"dds":0.0,"last_synced_commit":"cde08f16282a08900b15de480645c1661147380c"},"previous_names":["enthusiastic-js/form-observer"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enthusiastic-js%2Fform-observer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enthusiastic-js%2Fform-observer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enthusiastic-js%2Fform-observer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enthusiastic-js%2Fform-observer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/enthusiastic-js","download_url":"https://codeload.github.com/enthusiastic-js/form-observer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246620478,"owners_count":20806780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["form","html","js","lit","observer","preact","progressive-enhancement","react","solid","svelte","validation","vue","web"],"created_at":"2024-10-25T15:40:54.086Z","updated_at":"2025-04-01T16:30:54.593Z","avatar_url":"https://github.com/enthusiastic-js.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nNOTE: This file needs to be kept in sync with the `/packages/core/README.md` file.  Everything in here (except the `JS Framework Integrations` section unique to this file) should basically be copy-pasted from there.\n--\u003e\n\n# Form Observer\n\nA simple utility for reacting to events from a form's fields.\n\n## Features and Benefits\n\n- **Performant**: The `Form Observer` leverages [event delegation](https://gomakethings.com/why-is-javascript-event-delegation-better-than-attaching-events-to-each-element/) to minimize memory usage. Moreover, it easily integrates into _any_ JS framework _without_ requiring state -- giving your app a significant boost in speed.\n- **No Dependencies**: The `Form Observer` packs _a lot_ of power into a _tiny_ bundle to give your users the best experience. The **entire `@form-observer/core` library** is only 3.2kb minified + gzipped. (If you choose to use a [JS Framework Integration](./docs/form-validity-observer/integrations/README.md) instead, then the _total_ bundle size is only 3.5kb minified + gzipped.)\n- **Simple and Familiar API**: The `Form Observer` gives you a clear, easy-to-use API that has a similar feel to the standardized observers, such as the [`Mutation Observer`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) and the [`Intersection Observer`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver).\n- **Framework Agnostic**: You can easily use this tool in a pure-JS application or in the JS framework of your choice. The simple API and great Developer Experience remain the same regardless of the tooling you use.\n- [**Web Component Support**](https://developer.mozilla.org/en-US/docs/Web/API/Web_components): Because the `Form Observer` is written with pure JS, it works with Web Components out of the box.\n- **Flexible**: Without requiring any additional setup, the `Form Observer` allows you to work with fields dynamically added to (or removed from) your forms, fields [externally associated](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#form) with your forms, and more.\n- **Easily Extendable**: If you have a set of sophisticated form logic that you'd like to reuse, you can [extend](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends) the `Form Observer` to encapsulate all of your functionality. We provide a [local storage](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-storage-observer) solution and a [form validation](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer) solution out of the box.\n\n## Install\n\n```\nnpm install @form-observer/core\n```\n\n## Quick Start\n\nHere's an example of how to track the fields that a user has visited:\n\n```html\n\u003c!-- HTML --\u003e\n\u003cform id=\"example\"\u003e\n  \u003ch1\u003eFeedback Form\u003c/h1\u003e\n  \u003clabel for=\"full-name\"\u003eFull Name\u003c/label\u003e\n  \u003cinput id=\"full-name\" name=\"full-name\" type=\"text\" required /\u003e\n\n  \u003clabel for=\"rating\"\u003eRating\u003c/label\u003e\n  \u003cselect id=\"rating\" name=\"rating\" required\u003e\n    \u003coption value=\"\" selected disabled\u003ePlease Choose a Rating\u003c/option\u003e\n    \u003coption value=\"horrible\"\u003eHorrible\u003c/option\u003e\n    \u003coption value=\"okay\"\u003eOkay\u003c/option\u003e\n    \u003coption value=\"great\"\u003eGreat\u003c/option\u003e\n  \u003c/select\u003e\n\u003c/form\u003e\n\n\u003clabel for=\"comments\"\u003eAdditional Comments\u003c/label\u003e\n\u003ctextarea id=\"comments\" name=\"comments\" form=\"example\"\u003e\u003c/textarea\u003e\n\n\u003cbutton type=\"submit\" form=\"example\"\u003eSubmit\u003c/button\u003e\n```\n\n```js\n/* JavaScript */\nimport { FormObserver } from \"@form-observer/core\";\n// or import FormObserver from \"@form-observer/core/FormObserver\";\n\nconst form = document.querySelector(\"form\");\nconst observer = new FormObserver(\"focusout\", (event) =\u003e event.target.setAttribute(\"data-visited\", String(true)));\nobserver.observe(form);\n// Important: Remember to call `observer.disconnect` or `observer.unobserve` when observer is no longer being used.\n\nform.addEventListener(\"submit\", handleSubmit);\n\nfunction handleSubmit(event) {\n  event.preventDefault();\n  const form = event.currentTarget;\n  const visitedFields = Array.from(form.elements).filter((e) =\u003e e.hasAttribute(\"data-visited\"));\n  // Do something with visited fields...\n}\n```\n\nOf course, you can use the `Form Observer` just as easily in JS Frameworks too\n\n**Svelte**\n\n```svelte\n\u003cform id=\"example\" bind:this={form} on:submit={handleSubmit}\u003e\n  \u003c!-- Internal Fields --\u003e\n\u003c/form\u003e\n\n\u003c!-- External Fields --\u003e\n\n\u003cscript\u003e\n  import { onMount } from \"svelte\";\n  import { FormObserver } from \"@form-observer/core\";\n  // or import FormObserver from \"@form-observer/core/FormObserver\";\n\n  let form;\n  const observer = new FormObserver(\"focusout\", (event) =\u003e event.target.setAttribute(\"data-visited\", String(true)));\n  onMount(() =\u003e {\n    observer.observe(form);\n    return () =\u003e observer.disconnect();\n  });\n\n  function handleSubmit(event) {\n    event.preventDefault();\n    const visitedFields = Array.from(event.currentTarget.elements).filter((e) =\u003e e.hasAttribute(\"data-visited\"));\n    // Do something with visited fields...\n  }\n\u003c/script\u003e\n```\n\n**React**\n\n```jsx\nimport { useEffect, useRef } from \"react\";\nimport { FormObserver } from \"@form-observer/core\";\n// or import FormObserver from \"@form-observer/core/FormObserver\";\n\nfunction MyForm() {\n  // Watch Form Fields\n  const form = useRef(null);\n  useEffect(() =\u003e {\n    const observer = new FormObserver(\"focusout\", (event) =\u003e event.target.setAttribute(\"data-visited\", String(true)));\n\n    observer.observe(form.current);\n    return () =\u003e observer.disconnect();\n  }, []);\n\n  // Submit Handler\n  function handleSubmit(event) {\n    event.preventDefault();\n    const visitedFields = Array.from(event.currentTarget.elements).filter((e) =\u003e e.hasAttribute(\"data-visited\"));\n    // Do something with visited fields...\n  }\n\n  return (\n    \u003c\u003e\n      \u003cform id=\"example\" ref={form} onSubmit={handleSubmit}\u003e\n        {/* Internal Fields */}\n      \u003c/form\u003e\n\n      {/* External Fields */}\n    \u003c/\u003e\n  );\n}\n```\n\nInterested in learning more? Check out our [documentation](https://github.com/enthusiastic-js/form-observer/tree/main/docs). A great place to start would be our docs for the [`Form Observer` API](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-observer/README.md#api) or our [guides](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-observer/guides.md) for common use cases.\n\nToo eager to bother with documentation? Feel free to play with our library on [StackBlitz](https://stackblitz.com/@ITenthusiasm/collections/form-observer-examples) or in your own application! All of our tools have detailed JSDocs, so you should be able to learn all that you need to get started from within your IDE.\n\n## Solutions to Common Problems\n\nTwo common problems that developers need to solve for their complex web forms are:\n\n1. Storing a user's form progress in `localStorage`\n2. Validating a form's fields as a user interacts with them\n\nOur library provides solutions for these problems out of the box.\n\n### `localStorage` Solution\n\n```js\n/* JavaScript */\nimport { FormStorageObserver } from \"@form-observer/core\";\n// or import FormStorageObserver from \"@form-observer/core/FormStorageObserver\";\n\nconst form = document.querySelector(\"form\");\nconst observer = new FormStorageObserver(\"change\");\nobserver.observe(form);\n// Important: Remember to call `observer.disconnect` or `observer.unobserve` when observer is no longer being used.\n\nform.addEventListener(\"submit\", handleSubmit);\n\nfunction handleSubmit(event) {\n  event.preventDefault();\n  FormStorageObserver.clear(form); // User no longer needs their progress saved after a form submission\n}\n```\n\nNotice that the code required to get the `localStorage` feature up and running is almost exactly the same as the code that we showed in the [Quick Start](#quick-start). All that we did was switch to a feature-focused version of the `FormObserver`. We also setup an event handler to clear any obsolete `localStorage` data when the form is submitted.\n\nThere's even more that the `FormStorageObserver` can do. Check out our [`FormStorageObserver` documentation](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-storage-observer/README.md) for additional details.\n\n### Form Validation Solution\n\n```js\n/* JavaScript */\nimport { FormValidityObserver } from \"@form-observer/core\";\n// or import FormValidityObserver from \"@form-observer/core/FormValidityObserver\";\n\nconst form = document.querySelector(\"form\");\nform.noValidate = true;\n\nconst observer = new FormValidityObserver(\"focusout\");\nobserver.observe(form);\n// Important: Remember to call `observer.disconnect` or `observer.unobserve` when observer is no longer being used.\n\nform.addEventListener(\"submit\", handleSubmit);\n\nfunction handleSubmit(event) {\n  event.preventDefault();\n  const success = observer.validateFields({ focus: true });\n\n  if (success) {\n    // Submit data to server\n  }\n}\n```\n\nAgain, notice that the code required to get the form validation feature up and running is very similar to the code that we showed in the [Quick Start](#quick-start). The main thing that we did here was switch to a feature-focused version of the `FormObserver`. We also leveraged some of the validation-specific methods that exist uniquely on the `FormValidityObserver`.\n\nIf you want to use _accessible_ error messages instead of the browser's native error bubbles, you'll have to make some slight edits to your markup. _But these are the edits that you'd already be making to your markup anyway_ if you wanted to use accessible errors.\n\n```html\n\u003c!-- HTML --\u003e\n\u003cform id=\"example\"\u003e\n  \u003ch1\u003eFeedback Form\u003c/h1\u003e\n  \u003clabel for=\"full-name\"\u003eFull Name\u003c/label\u003e\n  \u003cinput id=\"full-name\" name=\"full-name\" type=\"text\" required aria-describedby=\"full-name-error\" /\u003e\n  \u003c!-- Add accessible error container here --\u003e\n  \u003cdiv id=\"full-name-error\"\u003e\u003c/div\u003e\n\n  \u003clabel for=\"rating\"\u003eRating\u003c/label\u003e\n  \u003cselect id=\"rating\" name=\"rating\" required aria-describedby=\"rating-error\"\u003e\n    \u003coption value=\"\" selected disabled\u003ePlease Choose a Rating\u003c/option\u003e\n    \u003coption value=\"horrible\"\u003eHorrible\u003c/option\u003e\n    \u003coption value=\"okay\"\u003eOkay\u003c/option\u003e\n    \u003coption value=\"great\"\u003eGreat\u003c/option\u003e\n  \u003c/select\u003e\n  \u003c!-- And Here --\u003e\n  \u003cdiv id=\"rating-error\"\u003e\u003c/div\u003e\n\u003c/form\u003e\n\n\u003clabel for=\"comments\"\u003eAdditional Comments\u003c/label\u003e\n\u003ctextarea id=\"comments\" name=\"comments\" form=\"example\"\u003e\u003c/textarea\u003e\n\n\u003cbutton type=\"submit\" form=\"example\"\u003eSubmit\u003c/button\u003e\n```\n\nAll that we had to do was add `aria-describedby` attributes that pointed to [accessible error message containers](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA21#example-2-identifying-errors-in-data-format) for our form fields.\n\nThere's _**much**, much more_ that the `FormValidityObserver` can do. Check out our [`FormValidityObserver` documentation](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/README.md) for additional details.\n\n## JS Framework Integrations\n\nJust as there isn't much of a benefit to wrapping the [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) or the [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) in a framework-specific package, we don't believe that there's any significant benefit to wrapping the `FormObserver` or the `FormStorageObserver` in a framework-specific package. These tools plug-and-play directly into any web application with ease -- whether the application uses pure JS or a JS framework. Consequently, we currently _do not_ provide framework-specific wrappers for most of our observers.\n\nThat said, we _do_ provide framework-specific wrappers for the `FormValidityObserver`. These wrappers technically aren't necessary since the full power of the `FormValidityObserver` is available to you in any JS framework as is. However, the big selling point of these wrappers is that they take advantage of the features in your framework (particularly, features like props spreading) to reduce the amount of code that you need to write to leverage the `FormValidityObserver`'s advanced features; so it's worth considering using them. We currently provide `FormValidityObserver` wrappers for the following frameworks:\n\n- [Svelte](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/svelte.md) (`@form-observer/svelte`)\n- [React](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/react.md) (`@form-observer/react`)\n- [Vue](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/vue.md) (`@form-observer/vue`)\n- [Solid](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/solid.md) (`@form-observer/solid`)\n- [Lit](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/lit.md) (`@form-observer/lit`)\n- [Preact](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/preact.md) (`@form-observer/preact`)\n\nFor your convenience, these libraries re-export the tools provided by `@form-observer/core` -- allowing you to consolidate your imports. For instance, you can import the `FormObserver`, the `FormStorageObserver`, the `FormValidityObserver`, and the _Svelte-specific_ version of the `FormValidityObserver` all from `@form-observer/svelte` if you like.\n\nTo learn more about _how_ these wrappers minimize your code, see our general documentation on [framework integrations](https://github.com/enthusiastic-js/form-observer/tree/main/docs/form-validity-observer/integrations/README.md).\n\nLive Examples of the `FormValidityObserver` on `StackBlitz`:\n\n- [Core](https://stackblitz.com/edit/form-observer-core-example?file=index.html,src%2Fmain.ts)\n- [Svelte Integration](https://stackblitz.com/edit/form-observer-svelte-example?file=src%2FApp.svelte)\n- [React Integration](https://stackblitz.com/edit/form-observer-react-example?file=src%2FApp.tsx)\n- [Vue Integration](https://stackblitz.com/edit/form-observer-vue-example?file=src%2FApp.vue)\n- [Solid Integration](https://stackblitz.com/edit/form-observer-solid-example?file=src%2FApp.tsx)\n- [Lit Integration](https://stackblitz.com/edit/form-observer-lit-example?file=src%2Flit-example.ts)\n- [Preact Integration](https://stackblitz.com/edit/form-observer-preact-example?file=src%2Fapp.tsx)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenthusiastic-js%2Fform-observer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenthusiastic-js%2Fform-observer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenthusiastic-js%2Fform-observer/lists"}