References

Beginner-friendly references for web development, with live, editable examples.

The HTML formenctype attribute

Attribute All modern browsers Updated
In short

The HTML formenctype attribute sets the encoding used when one specific button submits a form with POST. Use formenctype="multipart/form-data" on an upload button so file contents are sent. It overrides the form's enctype and has no effect on GET submissions.

Overview

The HTML formenctype attribute sets how form data is encoded when one particular submit button sends the form. It overrides the form's enctype for that submission and accepts the same three values, application/x-www-form-urlencoded, multipart/form-data and text/plain.

The encoding only matters for POST. A GET submission always puts the fields in the URL's query string, so a formenctype on a GET button is ignored. Pair it with formmethod="post" unless the form already posts. An unknown value, such as application/json, falls back to URL encoding.

The usual reason to reach for it is a file. With the default URL-encoded format, a file input sends nothing but the file's name. Setting formenctype="multipart/form-data" on an upload button sends the file's contents, while the other buttons in the same form keep the form's encoding.

Avoid text/plain outside debugging. The HTML standard describes it as a format meant for humans that a program can't reliably parse, because nothing separates a line break inside a value from the one that ends it.

Syntax

<form action="/profile" method="post">
  <label>Name <input type="text" name="display_name"></label>
  <label>Photo <input type="file" name="avatar"></label>
  <button>Save name</button>
  <button formenctype="multipart/form-data" formaction="/profile/avatar">Upload photo</button>
</form>

Values

Value
application/x-www-form-urlencoded | multipart/form-data | text/plain

Example

Live example 
<form id="up" action="/upload" method="post">
  <input type="file" name="photo" aria-label="Photo">
  <button>Default</button>
  <button formenctype="multipart/form-data">Multipart</button>
</form>
<p id="out">Pick a file, then click a button.</p>
<script>
document.getElementById('up').addEventListener('submit', function (e) {
  e.preventDefault();
  var type = e.submitter.getAttribute('formenctype') || this.enctype;
  var note = type === 'multipart/form-data' ? 'so the file itself is sent.' : 'so only the file name is sent.';
  document.getElementById('out').textContent = 'This button encodes the form as ' + type + ', ' + note;
});
</script>

Best practices

  • Use formenctype only when one button needs a different encoding. If every submission uploads files, set enctype on the form instead.
  • Always pair formenctype with a POST method, either on the form or through formmethod.
  • Check what the server expects. PHP, for example, only fills $_FILES for uploads sent as multipart/form-data.
  • Keep text/plain out of production forms.

Frequently asked questions

What does formenctype change when a button submits a form?
The formenctype attribute sets how one submit button encodes the form data it sends. It overrides the form's enctype for that button's POST submission.
Why does my form upload send only the file name?
A file becomes just its name under URL encoding or a GET request. Set formmethod=post and formenctype=multipart/form-data on the upload button, or the matching attributes on the form.
Does formenctype work with GET?
No, formenctype has no effect on a GET submission. GET always sends the fields in the URL's query string, so combine formenctype with formmethod=post.
When is formenctype useful?
The formenctype attribute helps when only one button in a form needs to upload files. That button can post as multipart/form-data while the others keep the form's usual encoding.
Can formenctype send JSON?
No, formenctype has no JSON option. A value such as application/json falls back to URL encoding, so build JSON in JavaScript and send it with fetch().
Should I use text/plain with formenctype?
No, keep formenctype=text/plain for debugging. The HTML standard warns that text/plain payloads can't be reliably read by a program.
formaction formmethod