Skip to content

docs(WebAPI): call out duplicate keys on FormData iteration methods #45584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MeGaurav4 wants to merge 2 commits into
base: main
Choose a base branch
from
+9 −0
Open

docs(WebAPI): call out duplicate keys on FormData iteration methods #45584

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
087a303
docs(WebAPI): call out duplicate keys on FormData iteration methods
MeGaurav4 Sep 9, 2026
efef491
Use GFM alert syntax for FormData duplicate-key notes
MeGaurav4 Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions files/en-us/web/api/formdata/entries/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ browser-compat: api.FormData.entries

The **`FormData.entries()`** method returns an [iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) which iterates through all key/value pairs contained in the {{domxref("FormData")}}. The key of each pair is a string, and the value is either a string or a {{domxref("Blob")}}.

> [!NOTE]
> Unlike [`Map`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) entries, `FormData` entries are not necessarily unique by key. A form can contain multiple elements with the same name, so the same key may appear in more than one pair while iterating. To retrieve all values associated with a single key, use the {{domxref("FormData.getAll()", "getAll()")}} method (or {{domxref("FormData.get()", "get()")}} for only the first value).

@Rob--W Rob--W Sep 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The entries method provides key-value pairs, so prescribing the use of get or getAll may be confusing.

I suggest dropping them; an explicit mention warning about the disconnect between the value and get() could make sense for clarity. For example, something like this:

Suggested change
> Unlike [`Map`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) entries, `FormData` entries are not necessarily unique by key. A form can contain multiple elements with the same name, so the same key may appear in more than one pair while iterating. To retrieve all values associated with a single key, use the {{domxref("FormData.getAll()", "getAll()")}} method (or {{domxref("FormData.get()", "get()")}} for only the first value).
> Unlike [`Map`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) entries, `FormData` entries are not necessarily unique by key. A form can contain multiple elements with the same name, so the same key may appear in more than one pair while iterating. Past the first entry, the value may differ from the return value of {{domxref("FormData.get()", "get()")}} which returns the first value associated with the key.


## Syntax

```js-nolint
Expand Down
3 changes: 3 additions & 0 deletions files/en-us/web/api/formdata/keys/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ browser-compat: api.FormData.keys

The **`FormData.keys()`** method returns an [iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) which iterates through all keys contained in the {{domxref("FormData")}}. The keys are strings.

> [!NOTE]
> Unlike [`Map`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) keys, `FormData` keys are not necessarily unique. A form can contain multiple elements with the same name, so the same key may appear more than once while iterating. To retrieve all values associated with a single key, use the {{domxref("FormData.getAll()", "getAll()")}} method (or {{domxref("FormData.get()", "get()")}} for only the first value).

## Syntax

```js-nolint
Expand Down
3 changes: 3 additions & 0 deletions files/en-us/web/api/formdata/values/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ browser-compat: api.FormData.values

The **`FormData.values()`** method returns an [iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) which iterates through all values contained in the {{domxref("FormData")}}. The values are strings or {{domxref("Blob")}} objects.

> [!NOTE]
> `FormData` keys are not necessarily unique. A form can contain multiple elements with the same name, so values sharing one key each appear while iterating. To retrieve all values associated with a single key, use the {{domxref("FormData.getAll()", "getAll()")}} method (or {{domxref("FormData.get()", "get()")}} for only the first value).

## Syntax

```js-nolint
Expand Down