The form and its request

1. A link with blanks to fill in

The web's first interaction was the link: a fixed URL, followed on a click. Its second was the form. Fill-out forms arrived with NCSA Mosaic 2.0 around the turn of 1994 and were written into the HTML 2.0 standard (RFC 1866) in 1995, and they are still how people sign up, search, buy, report and apply.

The simplest way to understand a form is as a parameterized link. A link to a list of easy trails that allow dogs has its question built into the URL:

A form asks the same question but lets the person fill in the blanks. Each control supplies one parameter, and pressing the button builds the URL and follows it:

Choose "Easy," tick the box, press the button, and the browser goes to /trails/?difficulty=easy&dogs=yes, the very URL the link held. The server cannot tell the two apart, and it does not need to. A form that only asks a question, such as a search or a filter, is exactly this: a link whose query string the person writes by choosing.

A form can do one thing a link cannot: send a request with a body, using POST, to change something on the server. Everything else on this page builds on those two ideas. A form with method="get" is a link with blanks; a form with method="post" is a letter the browser writes and mails for you. Patterns: The form already talks makes the same point from the network side: a form is already a complete HTTP client.

2. The pieces of a form

Every form, however long, is made of the same few kinds of parts. Learn to spot them and you can read any form, predict what it sends, and see what it is missing.

• The <form> element holds everything and says where the data goes and how: its action and method. Section 3 covers its attributes.
• Controls are the things a person fills in or chooses: <input> in its many types, <select>, <textarea>. Each control that sends data has a name, which becomes the key in the request, and a value, which is whatever the control holds when the form is submitted. Its id is for the page: labels, scripts and CSS find the control by it. Form Fields covers every control and exactly what each one sends.
• Labels name the controls for people and for assistive technology. A <label> points at its control with for holding the control's id. A <fieldset> with a <legend> names a group of controls that answer one question, such as a set of radio buttons. Organizing Forms covers both.
• Buttons submit the form. A <button> inside a form submits it unless its type says otherwise; type="button" makes a button that does nothing until a script gives it a job. A button can carry a name and value of its own, and attributes that change where the form goes, as section 8 shows.
• Messages, hints before anyone types and errors after, go in <output> elements tied to their control. They are part of the page, never part of the request. Organizing Forms explains the pattern.

Here are all five in the smallest useful form. The <form-field> element holds one label, its control and its messages together, and the <br> elements keep it readable with no CSS; Organizing Forms explains why this course writes every field this way.

Read it as the browser will. The form posts to /api/echo. It has one control that sends data, named email, which must be filled in and must look like an address. It has one button, which submits. When the person presses it, one pair goes out: email= followed by what they typed. The label, the hint, the error and the custom element around them are for the person and never leave the page.

3. The form element

The <form> element's attributes are the instructions for the request. Most forms need only the first two.

Two of these defaults catch people. A form with no method sends its data in the URL, which is wrong for anything private, so write the method every time, even when it is get. And HTML forms know only GET and POST: method="put" is not an error the browser reports; it is quietly a GET. Servers that want PUT or DELETE from a plain form usually accept a POST with a hidden field such as _method that names the real intent, a convention the film shows.

An action that already has a query string loses it on a GET submission. The browser replaces the whole query with the form's data, so action="/trails/?sort=new" submits to /trails/?difficulty=easy, not ?sort=new&difficulty=easy. To send a fixed parameter with a GET form, put it in a hidden field. A fragment, the part after #, survives.

4. What happens when you press the button

The HTML standard defines form submission as an exact algorithm. Reduced to its seven main steps, it runs like this:

1. Find the submitter. The submitter is the button that started the submission. If the person pressed Enter in a text box, it is the form's first submit button. If a script started it, it is whatever button the script named, or the form itself.
2. Validate. Unless the form has novalidate or the submitter has formnovalidate, the browser runs constraint validation: it checks every control's constraints (required, type, pattern, min, maxlength and the rest). If any fail, it stops, focuses the first problem and shows a message. Nothing is sent.
3. Fire the submit event. Scripts listening on the form can read it and cancel it with preventDefault(), usually to send the data themselves.
4. Build the entry list. The entry list is the list of name and value pairs to send, collected from the form's controls in document order. Section 5 covers exactly which controls make it in. As the list is built, the browser fires a formdata event, the last chance for a script to add or change an entry.
5. Serialize. The entry list is encoded as the enctype says, or into a query string for GET.
6. Build the request. The method and the action fill the first line; the encoding fills the Content-Type header; the serialized data becomes the query string or the body.
7. Navigate. The browser sends the request and shows the response in the target: the current page, a new tab, or a frame. Back, reload and history all work, because this is an ordinary navigation.

The order explains several things that otherwise look like bugs. The entry list is built after the submit event, so a script that changes a field's value in its submit handler changes what is sent. A form whose fields are invalid never fires submit at all, so a submit handler is not the place to discover that a required field is empty; the browser's invalid event is. And a submission attempt marks every field as touched, so after a failed submit, CSS's :user-invalid matches every field that is still wrong, not only the ones the person visited.

Enter submits

Pressing Enter in a single-line text box submits the form. The standard calls this implicit submission, and it works by clicking the form's default button, the first submit button in the form's source order. Two consequences follow. The first button's name and value are sent, as if it had been pressed, so put the primary action first. And if that first button is disabled, Enter does nothing. A form with no submit button at all still submits on Enter, but only if it has a single text-like field; with two or more, Enter does nothing, which is one more reason every form should have a real button.

Submitting from a script: requestSubmit(), not submit()

A script can start a submission too, and there are two methods for it that look interchangeable and are not. form.submit() is the old one. The standard says it submits the form "bypassing interactive constraint validation and without firing a submit event": it skips steps 2 and 3 entirely. A required field left empty is sent empty, and every submit listener on the page, including the one that was going to send the data with fetch, is silently passed over.

form.requestSubmit() does what a button press does: it validates, fires submit, and either can stop it. Pass it a submit button and that button becomes the submitter, its name and value are sent, and its override attributes from section 8 apply. It throws a TypeError if the argument is not a submit button and a NotFoundError if the button belongs to another form. It is Baseline widely available, supported across browsers since September 2022.

Older tutorials, including earlier versions of this course's notes, describe submit() as running validation and firing the event. It does not. Use requestSubmit(). Script that takes over submission entirely, listening for submit and sending the data itself, is covered in Events: forms.

5. What gets sent, and what does not

Step 4 walks the form's controls in document order and decides, control by control, whether each one contributes a pair. The rules are short and every one of them surprises someone:

Three of these rules do daily damage. The missing name is the most common reason a field "is not arriving" at the server: a control with an id and a label looks finished on screen and sends nothing. The unchecked box means a server cannot tell "unticked" from "this form never had that box"; code that reads a checkbox should treat a missing key as no, and a form that needs an explicit "no" should use two radio buttons. Disabled versus readonly is a choice about the request, not just the look: disable a field to leave it out, make it readonly to show it and send it. Neither one protects anything; anyone can remove the attribute in DevTools, as Form Security shows.

Two smaller rules complete the list. Controls inside a <datalist> are skipped, and a hidden input named _charset_ is filled in by the browser with the encoding it used, a fossil from the days when not everything was UTF-8.

How the pairs are written

The default encoding, application/x-www-form-urlencoded, writes the entry list the way a query string is written: each pair as name=value, pairs joined by &. Characters that would break that format are escaped. A space becomes +; most punctuation and every non-ASCII character becomes a percent sign followed by two hexadecimal digits for each byte of its UTF-8 encoding. Letters, digits and *-._ are left alone.

The escaping is why a value can safely contain & or =: a literal plus sign is sent as %2B, so a + on the wire always means a space. Every server framework decodes this for you. The thing to remember is the reverse: what arrives is always text. A number, a date, a checkbox, all arrive as strings, and the server decides what they mean.

6. GET and POST

The same entry list can travel two ways, and the choice decides who else gets to see it.

GET asks a question

With GET, the serialized data becomes the query string of the URL and the request has no body. That makes the result a URL like any other: it can be bookmarked, shared, reloaded and cached, and the back button works without a warning. HTTP calls GET safe: it asks for something and changes nothing, so the browser, a crawler or a prefetcher can repeat it freely. That is exactly right for a search, a filter, a sort or a page of results.

It is exactly wrong for anything private, because a URL is one of the leakiest places on the web. The query string of a GET form ends up in:

• the address bar, for anyone looking at the screen, and the browser history, for anyone who uses the device later;
• bookmarks and copied links, which carry it wherever they are pasted;
• the access logs of the server, and of any proxy, load balancer or analytics service in between, which are kept for months and read by people who never saw the form;
• the Referer header of requests the results page makes to its own site. Requests to other sites get only the origin by default, under the browser's strict-origin-when-cross-origin referrer policy, unless a page has loosened it.

A password, an email address, a health question or anything typed in confidence must never go out by GET. HTTPS does not help here: it encrypts the URL on the wire, but the history, the logs and the screen all see it in the clear. URLs also have practical length limits; many servers refuse a request line longer than about 8 KB by default, so a long message does not belong in one.

POST makes a change

With POST, the serialized data becomes the request body and the URL stays as the action wrote it. Use it whenever the request does something: creates an account, places an order, sends a message, deletes a report. POST is not safe and not idempotent; sending it twice may do it twice, which is why the browser asks before reloading a page that was the answer to a POST. A well-behaved server answers a successful POST with a redirect, status 303, to an ordinary page, so that reloading that page repeats a harmless GET instead of the order. This is called Post/Redirect/Get.

POST keeps the data out of the URL, and that is all it does. The body is as readable as the URL to anyone on the network unless the connection is HTTPS, and the server and DevTools read it in full. POST is not encryption, and it is not security. Patterns: The form already talks shows both requests arriving at /api/echo, headers and all.

7. Files, and the other encodings

A POST body can be written three ways, chosen with enctype. Patterns: What to send compares them in depth, together with the JSON a script can send; here is what matters for HTML forms.

multipart/form-data, for files

A URL-encoded body is one line of text, and a file is not text. To upload a file, a form needs method="post" and enctype="multipart/form-data". The browser then writes the body as a stack of parts, one per entry, divided by a boundary string it invents and names in the Content-Type header. Each part has its own small headers, and a file's part carries its file name, its type and its bytes, unencoded:

Forget the enctype and nothing fails, which is the trouble. The browser sends photo=note.txt, the file's name and not one byte of the file, and the server receives a perfectly valid form with no upload in it. If no file is chosen, a multipart form still sends the part, with an empty file name and no content. Multipart works for forms without files too; it is simply larger, so the default stays URL-encoded.

text/plain, for almost nothing

The third value writes each pair as name=value on its own line, with no escaping at all. The standard's own description is that such payloads "are not reliably interpretable by computer, as the format is ambiguous": a value that contains a line break or an = cannot be told apart from the separators. It is fine for a human to read in a debugging tool and for nothing else. Do not use it to send data a program must parse.

And no JSON

No enctype sends JSON. An HTML form sends URL-encoded or multipart data, and that is all; JSON needs a script that takes over the submission and builds the request with fetch. A server that accepts only JSON therefore breaks the form for anyone whose script did not run. The film's closing chapters show the progressive answer: a server that reads the Content-Type and accepts both.

8. The button has a say

A form's attributes set its defaults. The button that submits it, the submitter, can add to the data and override every one of those defaults for its own submission.

Buttons with a name and value

A submit button with a name and value adds that pair to the entry list when it is the one pressed, and only then. That lets one form offer several actions and lets the server tell them apart:

Press the first and the server receives action=send; press the second and it receives action=draft. With <button>, the value is separate from the visible text, so the server's key does not change when the label is reworded or translated. An <input type="submit"> works too, but its value is also its label, so the server ends up matching on display text.

Overriding the form

Five attributes on a submit button replace the form's own settings, for that button's submission only:

They work on <button type="submit">, <input type="submit"> and <input type="image">, and they apply when that button is the submitter, whether it was clicked, reached by Enter as the default button, or passed to requestSubmit(). One form can therefore write quite different requests:

Image buttons

<input type="image"> is a submit button drawn as a picture. It needs an alt, which is its accessible name. Instead of a name and value, it sends where it was clicked, in pixels from the image's top-left corner, as two pairs: pin.x=30&pin.y=12. Activated from the keyboard it sends pin.x=0&pin.y=0. Unless the coordinates really matter, as on a clickable map, a <button> with an <img> inside is simpler, sends a proper value and is styled like every other button.

Know which buttons submit

A <button> with no type inside a form is a submit button. A button meant to open a menu or toggle a panel, written without type="button", submits the form when pressed, and the page reloads before the script runs. Write the type on every button, every time. Form Fields covers the button types, and why type="reset" is best left out.

9. Beyond the form element

Controls outside the form: the form attribute

A control belongs to the form it sits inside. It can also belong to a form somewhere else in the document: give the form an id, and give the control form with that id. The control then takes part in the submission like any other: it is validated, its pair is added to the entry list, and a submit button outside the form submits it. Forms cannot be nested, so this is also how one control can serve a form while sitting inside the layout of another part of the page.

Entries are collected in document order, so trail arrives after everything inside the form. The attribute works on every form control and on <fieldset> and <output>. It is an escape hatch: the source no longer shows what the form contains, so use it only when the layout leaves no better choice, as Organizing Forms advises.

method="dialog": a form that sends nothing

Inside a <dialog> element, a form with method="dialog" does not make a request. Submitting it closes the dialog, and the submitter's value becomes the dialog's returnValue, which a script reads in the dialog's close event. That makes a confirmation box a few lines of markup:

The rest of the lifecycle still runs first: constraints are checked and submit fires, so a required field inside a dialog blocks its Cancel button too. The usual fix is a Cancel button with formmethod="dialog" and formnovalidate inside an ordinary POST form, so that Save sends the data and Cancel just closes the box. Nothing in the form is sent and nothing is cleared; the fields keep their values for the next time the dialog opens. A form with method="dialog" that is not inside an open dialog does nothing at all.

10. One form, every surprise

The demo is a trail permit request with every rule from this page in it: a field with an id and no name, a readonly permit number, a disabled discount code, a hidden source, a select with two hazards chosen, notes with a line break and an ampersand, three checkboxes, a file input, and a trail field written after the form and joined to it with the form attribute. Every field is already filled in. Four submitters send it four ways, each to /api/echo in a new tab:

• Send (POST) submits as the form says: URL-encoded, in the body, with action=send.
• Preview (GET) has formmethod="get": the same pairs move into the address bar, and the body is empty.
• Send as multipart has formenctype="multipart/form-data": each pair becomes a part, and a chosen file arrives whole.
• Map pin is an image button: in place of action, it sends pin.x and pin.y.

Pressing Send produces this body, one line in the echo, broken here at each pair:

No nickname, no coupon, no news. The readonly permit and the hidden source are there. The file input with no file chosen sends an empty photo=, and trail comes last because it comes last in the document.

11. Summary