object-to-formdata

object-to-formdata

Serialize JavaScript objects into FormData. Supports nested objects, arrays, dates, files, blobs, and configurable key formatting with no runtime dependencies.

Installation

npm install object-to-formdata

Other package managers:

yarn add object-to-formdata
pnpm add object-to-formdata
bun add object-to-formdata

Usage

import { serialize } from "object-to-formdata";

const formData = serialize({
  name: "Ada",
  active: true,
  tags: ["admin", "editor"],
  profile: {
    age: 36,
  },
});

formData.get("name"); // "Ada"
formData.getAll("tags[]"); // ["admin", "editor"]
formData.get("profile[age]"); // "36"

CommonJS is also supported:

const { serialize } = require("object-to-formdata");

TypeScript declarations are included with the package.

API

serialize(object?, options?, existingFormData?, keyPrefix?)

Serializes a value and returns a FormData instance.

object

The value to serialize. Objects and arrays are traversed recursively. Dates are converted to ISO strings, while File and Blob values are appended directly. undefined and symbol values are ignored.

Circular structures throw a TypeError.

options

Option	Default	Description
indices	false	Include array indices, such as items[0].
nullsAsUndefineds	false	Ignore null values instead of appending an empty string.
booleansAsIntegers	false	Serialize booleans as 1 or 0.
allowEmptyArrays	false	Append an empty string for empty arrays.
noAttributesWithArrayNotation	false	Omit array notation from non-file array keys.
noFilesWithArrayNotation	false	Omit array notation from file array keys.
dotsForObjectNotation	false	Use dots instead of brackets for nested object keys.

const formData = serialize(
  {
    users: [{ name: "Ada" }, { name: "Grace" }],
  },
  {
    indices: true,
    dotsForObjectNotation: true,
  },
);

formData.get("users[0].name"); // "Ada"

existingFormData

An existing FormData instance to append to. The same instance is returned.

const formData = new FormData();
formData.append("token", "abc123");

serialize({ name: "Ada" }, undefined, formData);

keyPrefix

An optional prefix for generated keys.

const formData = serialize({ name: "Ada" }, undefined, undefined, "user");

formData.get("user[name]"); // "Ada"

Runtime requirements

The runtime must provide FormData, either globally or through the existingFormData argument. Modern browsers and supported Node.js releases provide a global implementation.

Development

Run the test suite:

bun run test

Inspect the package contents before publishing:

bun pm pack --dry-run

License

MIT