https://github.com/nullvoxpopuli/form-data-utils
Utilities for working with the native FormData
https://github.com/nullvoxpopuli/form-data-utils
Last synced: 10 months ago
JSON representation
Utilities for working with the native FormData
- Host: GitHub
- URL: https://github.com/nullvoxpopuli/form-data-utils
- Owner: NullVoxPopuli
- License: mit
- Created: 2024-05-29T02:30:18.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-05T22:09:55.000Z (10 months ago)
- Last Synced: 2025-10-06T00:13:07.213Z (10 months ago)
- Language: TypeScript
- Size: 775 KB
- Stars: 29
- Watchers: 1
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# form-data-utils
[Demo](https://ember-primitives.pages.dev/6-utils/data-from-event.md)
A utility function for extracting the FormData as an object from the native ``
element, allowing more ergonomic of usage of _The Platform_'s default form/fields usage.
Each input within your `` should have a `name` attribute.
(or else the `` element doesn't know what inputs are relevant)
This will provide values for all types of controls/fields,
- input: text, checkbox (and checkbox arrays), radio, file, range, etc
- select
- behavior is fixed from browser default behavior, where
only the most recently selected value comes through in
the FormData. This fix only affects ``
- submitter (the button/etc that causes the form to submit (if it has a name attribute))
## Installation
```
npm add form-data-utils
```
## Usage
```gjs
import { dataFrom } from 'form-data-utils';
function handleSubmit(event) {
event.preventDefault();
let obj = dataFrom(event);
// ^ { firstName: "NVP", isHuman: null, }
}
First Name
Are you a human?
Submit
```
## Non-primitive values
In some cases, you might want to select values that aren't primitive types, e.g selecting a user from a list of users.
Unfortunately, FormData only supports strings. To work around this, `form-data-utils` provides some utility functions
to "attach" a non-primitive value to an element:
- `setValue(element: HTMLElement, value: unknown)` - binds a given value to a given element (value can be anything, e.g objects, arrays, etc)
- `deleteValue(element: HTMLElement)` - undoes a previous `setValue` call
After setting a value with `setValue`, that value will be considered by the `dataFrom` function.
> [!NOTE]
> The ideal way to call these functions will probably vary with the framework you're using.
For example, in [Ember.js](https://emberjs.com/), you would use these functions in a modifier that you can then apply to elements.
```gjs
import { dataFrom, deleteValue, setValue } from 'form-data-utils';
import { modifier } from 'ember-modifier';
// define the ember specific modifier
const associateValue = modifier((element, [value]) => {
setValue(element, value);
return () => deleteValue(element);
});
function handleSubmit(event) {
event.preventDefault();
let obj = dataFrom(event);
// ^ { admin: { id: 123, name: 'Sam...' }, user: { id: 321, name: 'Chris...' } }
}
{{#each users as |user|}}
{{user.name}}
{{/each}}
{{#each users as |user|}}
{{user.name}}
{{/each}}
Submit
```
`setValue` (and `deleteValue`) doesn't really care how you call it. It just needs an element and a value, that's it.
> [!NOTE]
> `setValue` only supports ` [!WARNING]
> The value given by `setValue` has priority. This means that providing both a `value` attribute *and* a value via `setValue` will result in the `value` attribute being ignored by `dataFrom`. However, you might still use the `value` attribute it to create a more meaningful html structure.
## Value types normalization
Another thing that `form-data-utils` does is to normalize the types of the values you get back from `dataFrom`. The following table lists the types you get back depending on the various controls available:
| Control | Type | Default (empty) value |
| ------------------------- | ------------- | ------------- |
| ` [!NOTE]
> `GivenValueType` here means the type of the value you passed in the `value` attribute **or** using the `setValue(element, value)` function.
## Contributing
See the [Contributing](CONTRIBUTING.md) guide for details.
## License
This project is licensed under the [MIT License](LICENSE.md).