{"id":23082588,"url":"https://github.com/runarberg/formsquare","last_synced_at":"2025-04-03T14:23:35.965Z","repository":{"id":5708023,"uuid":"53742992","full_name":"runarberg/formsquare","owner":"runarberg","description":"Serialize your HTML forms the smart way","archived":false,"fork":false,"pushed_at":"2023-01-05T16:13:53.000Z","size":1951,"stargazers_count":1,"open_issues_count":11,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-22T09:51:28.713Z","etag":null,"topics":["html-form","javascript","serializer"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/runarberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-12T17:02:56.000Z","updated_at":"2021-08-12T00:20:31.000Z","dependencies_parsed_at":"2023-01-13T13:40:08.537Z","dependency_job_id":null,"html_url":"https://github.com/runarberg/formsquare","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runarberg%2Fformsquare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runarberg%2Fformsquare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runarberg%2Fformsquare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runarberg%2Fformsquare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runarberg","download_url":"https://codeload.github.com/runarberg/formsquare/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247015230,"owners_count":20869515,"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":["html-form","javascript","serializer"],"created_at":"2024-12-16T14:55:33.918Z","updated_at":"2025-04-03T14:23:35.942Z","avatar_url":"https://github.com/runarberg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm](https://img.shields.io/npm/v/formsquare.svg)](https://www.npmjs.com/package/formsquare)\n[![Build Status](https://travis-ci.org/runarberg/formsquare.svg?branch=master)](https://travis-ci.org/runarberg/formsquare)\n[![Coverage Status](https://coveralls.io/repos/github/runarberg/formsquare/badge.svg)](https://coveralls.io/github/runarberg/formsquare)\n\nformsquare\n==========\n\n\u003e Turn your HTML5 forms into javascript objects the smart way.\n\n### Installation\n\n```\nnpm install --save formsquare\n```\n\n### Usage\n\n#### Module\n\n```js\nimport formsquare from \"formsquare\";\n\nformsquare.parse(form);\n\n// or\nformsquare.filter(myFilter).parse(form);\n```\n\nWhere `form` is an `HTMLFormElement` (like `document.forms[0]`) and\n`myFilter` is a predicate function (like `el =\u003e !el.disabled`) that\ndetermines which form elements to include.\n\n#### commonjs\n\nSame as above except import with:\n\n```js\nconst formsquare = require(\"formsquare\");\n```\n\n#### HTML\n\nDownload the [full script][script-full] or [minified script][script-min]\nand include this in your HTML file:\n\n```html\n\u003cscript src=\"formsquare.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  formsquare.parse(document.forms[0]);\n\u003c/script\u003e\n```\n\nOr download the [module][module-full] and import it:\n\n```html\n\u003cscript module\u003e\n  import formsquare from \"/path/to/module/formsquare.js\";\n\n  formsquare.parse(document.forms[0]);\n\u003c/script\u003e\n```\n\n#### [More examples below](#examples)\n\nWhat makes formsquare different\n-------------------------------\n\nFormsquare is yet another [square bracket notation][spec] form to\njavascript object parser, but smarter. Formsquare tries to be smart\nabout your form structure and keep open most possible mappings to\nvalid JSON objects. Formsquare will also take note of your HTML5 [form\nattributes][mdn/input#attr-form], even in [Internet\nExplorer][caniuse#form-attribute].\n\nFor the first part formsquare tries to retain the types of your form\nelements.\n\n* Inputs of type `checkbox` with no explicit value attribute get the\n  value `true` if it is checked, and `false` otherwise.\n* Inputs of type `number` and `range` gets it value casted to `number`.\n* Inputs of type `month`, `week`, `date`, and `datetime-local` will\n  get their values as a `Date` object. Invalid dates, retain their\n  original values.\n* All other elements get their value as `string`.\n\nSecondly formsquare won’t force you into a root object.\n\n* Form elements with explicit `name` attribute will nest inside an\n  object.\n* Form elements with a `name` starting with `[]` will nest inside an\n  array.\n* Form elements without an explicit `name` will either be a single\n  value (if it is the only element of the form) or an array.\n\nAnd finally formsquare tries retain the meaning of your checkboxes.\n\n* A single valued checkbox will be that value if checked, otherwise it\n  will be `null`.\n* A collection (2 or more) of valued checkboxes, sharing the name,\n  will collect all checked values into an array.\n* Explicit array checkboxes will always be collected in an array if\n  checked.\n\nThis means that you’ll now have more flexeble options in structuring\nyour HTML forms. If your form only takes a single number, just leave\nan unamed input of type `number`.\n\nExamples\n--------\n\n### Basic usage\n\n```html\n\u003cform id=\"my-form\"\u003e\n  \u003cinput name=\"foo\" value=\"bar\"\u003e\n  \u003cinput name=\"baz\" value=\"quux\" disabled\u003e\n\u003c/form\u003e\n```\n\n```js\nimport formsquare from \"formsquare\";\n\nconst form = document.getElementById(\"my-form\");\nconst filter = el =\u003e !el.disabled;\n\nformsquare.filter(filter).parse(form);\n//=\u003e {\"foo\": \"bar\"}\n```\n\n### Filters\n\nYou can call `formsquare.filter` with a predicate be returned a new\nparser that will filter all form elements by that predicate.\n\n```html\n\u003cform\u003e\n  \u003cinput value=\"foo\"\u003e\n  \u003cinput value=\"bar\" disabled\u003e\n\u003c/form\u003e\n\n\u003cform\u003e\n  \u003cinput value=\"foo\" disabled\u003e\n  \u003cinput value=\"bar\"\u003e\n\u003c/form\u003e\n\n\u003cform\u003e\n  \u003cinput value=\"foo\" disabled\u003e\n  \u003cinput value=\"bar\" class=\"hidden\"\u003e\n  \u003cinput value=\"baz\"\u003e\n\u003c/form\u003e\n```\n\n```js\nimport formsquare from \"formsquare\";\n\nconst { parse } = formsquare.filter(el =\u003e !el.disabled);\n\nparse(document.forms[0]);\n//=\u003e \"foo\"\n\nparse(document.forms[1]);\n//=\u003e \"bar\"\n\n// Filters can be chained\n\nformsquare\n  .filter(el =\u003e !el.disabled)\n  .filter(el =\u003e !el.classList.contains(\"hidden\"))\n  .parse(document.forms[2]);\n//=\u003e \"baz\"\n```\n\n### Simple forms\n\nAn empty form will always return `null`\n\n```html\n\u003cform id=\"empty-form\"\u003e\u003c/form\u003e\n```\n\n```js\nformsquare.parse(document.getElementById(\"empty-form\"));\n//=\u003e null\n```\n\nA form with a single element without an explicit name gives you a\nsingleton value.\n\n```html\n\u003cform id=\"singleton-form\"\u003e\n  \u003cinput type=\"number\" value=\"42\"\u003e\n\u003c/form\u003e\n```\n\n```js\nconst singletonForm = document.getElementById(\"singleton-form\");\nformsquare.parse(singletonForm);\n//=\u003e 42\n\nsingletonForm[0].type = \"text\";\nformsquare.parse(singletonForm);\n//=\u003e \"42\"\n```\n\n### Collections of forms\n\nYou can pass in an array or a [node list][mdn#node-list] of forms and\nit will be handled as a single form.\n\n```html\n\u003cform\u003e\n  \u003cinput type=\"number\" name=\"foo\" value=\"2\"\u003e\n  \u003cinput type=\"number\" name=\"bar\" value=\"5\"\u003e\n\u003c/form\u003e\n\n\u003cform\u003e\n  \u003cinput type=\"number\" name=\"foo\" value=\"42\"\u003e\n\u003c/form\u003e\n```\n\n```js\nformsquare.parse(document.forms);\n//=\u003e {\"foo\": [2, 42], \"bar\": 5}\n\n[...document.forms].map(formsquare.parse);\n//=\u003e [{\"foo\": 2, \"bar\": 5}, {\"foo\": 42}]\n```\n\n### Checkboxes\n\nIf your form needs a list of booleans, you only need to omit the value\nattribute:\n\n```html\n\u003cform id=\"checkbox-form\"\u003e\n  \u003cinput type=\"checkbox\" name=\"[]\"\u003e\n  \u003cinput type=\"checkbox\" name=\"[]\" checked\u003e\n\u003c/form\u003e\n```\n\n```js\nconst checkboxForm = document.getElementById(\"checkbox-form\");\nformsquare.parse(checkboxForm);\n//=\u003e [false, true]\n```\n\nCheckboxes with explicit values are handled differently:\n\n```js\ncheckboxForm[0].value = \"false\";\ncheckboxForm[1].value = \"on\";\n\nformsquare.parse(checkboxForm);\n//=\u003e [\"on\"]\n```\n\nAnd if no checkbox is checked, you will get the empty array:\n\n```js\ncheckboxForm[1].checked = false;\n\nformsquare.parse(checkboxForm);\n//=\u003e []\n```\n\n### Files\n\nInputs with the type of “file” (`\u003cinput type=\"file\"\u003e`) result in a\npromise containing the file object. File inputs with `multiple` set to\ntrue will result in promise of an array of such objects.\n\n```html\n\u003cform\u003e\n  \u003cinput type=\"file\"\u003e\n\u003c/form\u003e\n```\n\nGranted that a user uploaded the file `foo.txt` conatining the text\n`foo`:\n\n```js\nawait formsquare.parse(document.forms[0]);\n\n//=\u003e {\n//     body: \"Zm9v\",\n//     name: \"foo.txt\",\n//     type: \"text/plain\",\n//   }\n```\n\nAlternatives\n------------\n\nIf you want a more traditional form parser, you could take a look at\nany of these:\n\n* [form2js](https://www.npmjs.com/package/form2js)\n* [form-parse](https://www.npmjs.com/package/form-parse)\n* [form-serialize](https://www.npmjs.com/package/form-serialize)\n* [form-serializer](https://www.npmjs.com/package/form-serializer)\n* [get-form-data](https://www.npmjs.com/package/get-form-data)\n\n[module-full]: https://cdn.jsdelivr.net/npm/formsquare/dist/module/formsquare.js\n[script-full]: https://cdn.jsdelivr.net/npm/formsquare/dist/iife/formsquare.js\n[script-min]: https://cdn.jsdelivr.net/npm/formsquare/dist/iife/formsquare.min.js\n\n[caniuse#form-attribute]: http://caniuse.com/#feat=form-attribute\n[mdn/input#attr-form]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-form\n[mdn/node-list]: https://developer.mozilla.org/en-US/docs/Web/API/NodeList\n[spec]: https://www.w3.org/TR/html-json-forms/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunarberg%2Fformsquare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunarberg%2Fformsquare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunarberg%2Fformsquare/lists"}