{"id":11483,"library":"object-to-formdata","title":"Object to FormData Serializer","description":"object-to-formdata is a utility library for JavaScript that efficiently serializes plain JavaScript objects into `FormData` instances, a crucial browser API for sending data via `multipart/form-data` requests. Currently at version 4.5.1, it provides options to control how arrays, nulls, booleans, and object/array notation in keys are handled during serialization. The package is actively maintained with regular updates and bug fixes, indicated by its recent releases. Its primary differentiator is the configurable serialization logic, allowing developers to fine-tune how complex data structures are represented in `FormData` compared to manual construction or simpler serializers.","status":"active","version":"4.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/therealparmesh/object-to-formdata","tags":["javascript","form","formdata","object","object-to-formdata","submit","typescript"],"install":[{"cmd":"npm install object-to-formdata","lang":"bash","label":"npm"},{"cmd":"yarn add object-to-formdata","lang":"bash","label":"yarn"},{"cmd":"pnpm add object-to-formdata","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since version 3.0.0, there is no default export. Version 4.0.0 changed the named export from `formData` to `serialize`.","wrong":"import serialize from 'object-to-formdata'; // incorrect since v3","symbol":"serialize","correct":"import { serialize } from 'object-to-formdata';"},{"note":"For CommonJS environments, ensure you destructure the `serialize` function as it's a named export.","wrong":"const serialize = require('object-to-formdata'); // incorrect since v3","symbol":"serialize (CommonJS)","correct":"const { serialize } = require('object-to-formdata');"},{"note":"The library ships with TypeScript types. While FormData is a global Web API, this might be used for specific internal types if exposed.","symbol":"FormData (Type)","correct":"import type { FormData } from 'object-to-formdata';"}],"quickstart":{"code":"import { serialize } from 'object-to-formdata';\n\nconst userProfile = {\n  name: 'John Doe',\n  email: 'john.doe@example.com',\n  age: 30,\n  isActive: true,\n  roles: ['admin', 'editor'],\n  address: {\n    street: '123 Main St',\n    city: 'Anytown',\n    zip: '12345'\n  },\n  avatar: new File([''], 'avatar.png', { type: 'image/png' })\n};\n\nconst options = {\n  indices: true, // Serialize roles[0]=admin, roles[1]=editor\n  booleansAsIntegers: true, // Serialize isActive=1\n  nullsAsUndefineds: true, // Ignore null values\n  dotsForObjectNotation: false // Use brackets for objects (address[street])\n};\n\nconst formData = serialize(userProfile, options);\n\n// To see the contents (FormData is not directly iterable by value without special methods):\nfor (const pair of formData.entries()) {\n  console.log(`${pair[0]}: ${pair[1]}`);\n}\n\n// Example of appending to an existing FormData instance\nconst existingData = new FormData();\nexistingData.append('tenantId', '123-abc');\nconst combinedFormData = serialize({ metadata: 'important' }, {}, existingData);\n\nfor (const pair of combinedFormData.entries()) {\n  console.log(`Combined: ${pair[0]}: ${pair[1]}`);\n}","lang":"typescript","description":"Demonstrates basic serialization of a complex JavaScript object, including files, arrays, and nested objects, into a FormData instance using various configuration options, and appending to existing FormData."},"warnings":[{"fix":"Change your import statement to use named exports: `import { serialize } from 'object-to-formdata';`.","message":"Starting with version 3.0.0, the package removed its default export. Attempts to import it using `import serialize from 'object-to-formdata'` will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your import statement from `import { formData } from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.","message":"Version 4.0.0 introduced a breaking change by renaming the primary named export from `formData` to `serialize`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Set the `booleansAsIntegers` option to `true` in the configuration object: `serialize(object, { booleansAsIntegers: true })`.","message":"By default, boolean values (`true`/`false`) are serialized as the strings 'true'/'false'. If your backend expects integers (1/0), you need to configure this behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the `indices: true` option for indexed array keys, or `noAttributesWithArrayNotation: true` / `noFilesWithArrayNotation: true` to suppress bracket notation for non-file/file attributes respectively.","message":"Arrays are serialized with bracket notation by default (e.g., `items[]`). If you need indexed keys (e.g., `items[0]`), or no array notation for files/attributes, specific options are required.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"The named export was renamed. Change `import { formData } from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.","cause":"Attempting to use the old `formData` named export after upgrading to version 4.0.0 or higher.","error":"TypeError: (0 , object_to_formdata__WEBPACK_IMPORTED_MODULE_0__.formData) is not a function"},{"fix":"The package no longer has a default export. Change `import serialize from 'object-to-formdata';` to `import { serialize } from 'object-to-formdata';`.","cause":"Attempting to import `object-to-formdata` as a default export, which was removed in version 3.0.0.","error":"TypeError: object_to_formdata__WEBPACK_IMPORTED_MODULE_0__.default is not a function"},{"fix":"The library correctly serializes nested objects and arrays into appropriate `FormData` keys. When inspecting `FormData` via `console.log`, you'll see the flattened key-value pairs, which is how HTTP `multipart/form-data` works. Ensure your backend is configured to parse these nested key structures (e.g., using a library like `multer` in Node.js).","cause":"This is not an error but expected browser behavior. `FormData` itself flattens to key-value pairs where values are strings or `File`/`Blob` objects. Nested structures are flattened into keys like `parent[child]` or `array[0]`, not actual nested objects.","error":"FormData entries show '[object Object]' for nested objects or arrays instead of serialized keys."}],"ecosystem":"npm"}