https://github.com/xehrad/form-json
An HTMX extension for automatic type conversion in form data encoding. automatically converts values based on input types, ensuring correct data representation in JSON without requiring additional attributes or configuration.
https://github.com/xehrad/form-json
htmx htmx-extension json-encoder json-form
Last synced: 4 days ago
JSON representation
An HTMX extension for automatic type conversion in form data encoding. automatically converts values based on input types, ensuring correct data representation in JSON without requiring additional attributes or configuration.
- Host: GitHub
- URL: https://github.com/xehrad/form-json
- Owner: xehrad
- License: other
- Created: 2025-01-14T14:28:33.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-16T14:15:23.000Z (9 months ago)
- Last Synced: 2025-10-13T13:21:36.332Z (8 months ago)
- Topics: htmx, htmx-extension, json-encoder, json-form
- Language: JavaScript
- Homepage:
- Size: 263 KB
- Stars: 28
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# form-json
This is an [HTMX](https://htmx.org/) extension that enables the transformation of form data into a structured JSON object. The extension supports the [HTML JSON form](https://www.w3.org/TR/html-json-forms/) specification and works seamlessly with all examples outlined in the standard.
## Features
- **JSON Serialization**: Converts form inputs into a JSON object.
- **Nested Structures**: Supports complex nested structures with dot (`.`) or bracket (`[]`) notation.
- **Array and Object Handling**: Automatically detects arrays, objects, and scalar values based on field names and their indices.
- **Type Preservation**: Ensures correct typing for number, boolean, file, and other input types.
- **Compatibility with `htmx`**: Integrates with `htmx` events to set appropriate headers and handle form submissions.
## Install
Add the JavaScript file to your project and include it in your HTML:
```html
```
Enable the extension in your htmx configuration:
```html
...
```
## Usage
The extension automatically serializes `form data` into `JSON` for any form with the `hx-ext="form-json"` attribute. The resulting JSON object adheres to the [HTML JSON form](https://www.w3.org/TR/html-json-forms/) standard, supporting nested objects and arrays.
### Examples from the HTML JSON Forms Specification
#### Type Preservation
```html
```
#### Complex Nesting
```html
```
#### Hidden Value
There are two ways to send **hidden values** in a form:
1. Using a hidden input field (``).
2. Using `hx-vals` to inject custom values dynamically.
Note: that hidden input fields always send values as **strings**, which means if you're dealing with **Boolean** or **Number** types, you should use `hx-vals` to ensure the correct data type is sent.
```html
```
#### Merge Behavior
The algorithm does not lose data in that every piece of information ends up being submitted. But given the path syntax, it is possible to introduce clashes such that one may attempt to set an object, an array, and a scalar value on the same key.
```html
```
#### Append
an array irrespective of the number of its items, and without resorting to indices, one may use the append notation (only as the final step in a path)
```html
```
#### Complex Nesting
```html
```
## Attribute
### Attribute `ignore-deep-key`
Ignore Deep Key is Optional attribute to skip parsing keys to struct:
```html
```
### Attribute `ignore-drop-false-option`
By default, unchecked single checkboxes are **omitted** from the JSON output (same as HTML form submission behavior).
If you add the `ignore-drop-false-option` attribute to your ``, unchecked single checkboxes will instead be included with a `false` value.
```html
```
### Attribute `ignore-drop-false-option-array`
By default, unchecked checkboxes in a group (`name="options[]"`) are omitted, and only checked values are included in the array.
If you add the `ignore-drop-false-option-array` attribute to your ``, unchecked checkboxes in a group will explicitly push `false` into the array.
```html
A
B
C
```
## Development
To contribute, clone the repository and submit pull requests for features or bug fixes. Ensure all new functionality aligns with the [HTML JSON form](https://www.w3.org/TR/html-json-forms/) standard.
---
## ⭐️ Like it? Star it!
If this project saves you time or sparks ideas, please [⭐ star the repo](https://github.com/xehrad/form-json) — it really helps us grow the community.