diff options
Diffstat (limited to 'devdocs/html/element%2Finput%2Ffile.html')
| -rw-r--r-- | devdocs/html/element%2Finput%2Ffile.html | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/devdocs/html/element%2Finput%2Ffile.html b/devdocs/html/element%2Finput%2Ffile.html new file mode 100644 index 00000000..ba32c278 --- /dev/null +++ b/devdocs/html/element%2Finput%2Ffile.html @@ -0,0 +1,271 @@ +<header><h1><input type="file"></h1></header><div class="section-content"><p><a href="../input"><code><input></code></a> elements with <code>type="file"</code> let the user choose one or more files from their device storage. Once chosen, the files can be uploaded to a server using <a href="https://developer.mozilla.org/en-US/docs/Learn/Forms">form submission</a>, or manipulated using JavaScript code and <a href="https://developer.mozilla.org/en-US/docs/Web/API/File_API/Using_files_from_web_applications">the File API</a>.</p></div> +<h2 id="try_it">Try it</h2> +<div class="section-content"><iframe class="interactive is-tabbed-shorter-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/input-file.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe></div> +<h2 id="value">Value</h2> +<div class="section-content"> +<p>A file input's <a href="../input#value"><code>value</code></a> attribute contains a string that represents the path to the selected file(s). If no file is selected yet, the value is an empty string (<code>""</code>). When the user selected multiple files, the <code>value</code> represents the first file in the list of files they selected. The other files can be identified using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/File_API/Using_files_from_web_applications#getting_information_about_selected_files">input's <code>HTMLInputElement.files</code> property</a>.</p> <div class="notecard note" id="sect1"> <p><strong>Note:</strong> The value is <a href="https://html.spec.whatwg.org/multipage/input.html#fakepath-srsly" target="_blank">always the file's name prefixed with <code>C:\fakepath\</code></a>, which isn't the real path of the file. This is to prevent malicious software from guessing the user's file structure.</p> </div> +</div> +<h2 id="additional_attributes">Additional attributes</h2> +<div class="section-content"><p>In addition to the common attributes shared by all <a href="../input"><code><input></code></a> elements, inputs of type <code>file</code> also support the following attributes.</p></div> +<h3 id="accept">accept</h3> +<div class="section-content"> +<p>The <a href="../../attributes/accept"><code>accept</code></a> attribute value is a string that defines the file types the file input should accept. This string is a comma-separated list of <strong><a href="#unique_file_type_specifiers">unique file type specifiers</a></strong>. Because a given file type may be identified in more than one manner, it's useful to provide a thorough set of type specifiers when you need files of a given format.</p> <p>For instance, there are a number of ways Microsoft Word files can be identified, so a site that accepts Word files might use an <code><input></code> like this:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="mL1tFpAX7YTR/WZ4eqlGDMJYXpjVwNEj/UjUMlsrnfw=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> + <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>docpicker<span class="token punctuation">"</span></span> + <span class="token attr-name">accept</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>.doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> +</pre> +</div> +</div> +<h3 id="capture">capture</h3> +<div class="section-content"> +<p>The <a href="../../attributes/capture"><code>capture</code></a> attribute value is a string that specifies which camera to use for capture of image or video data, if the <a href="../../attributes/accept"><code>accept</code></a> attribute indicates that the input should be of one of those types. A value of <code>user</code> indicates that the user-facing camera and/or microphone should be used. A value of <code>environment</code> specifies that the outward-facing camera and/or microphone should be used. If this attribute is missing, the <a href="https://developer.mozilla.org/en-US/docs/Glossary/User_agent">user agent</a> is free to decide on its own what to do. If the requested facing mode isn't available, the user agent may fall back to its preferred default mode.</p> <div class="notecard note" id="sect2"> <p><strong>Note:</strong> <code>capture</code> was previously a Boolean attribute which, if present, requested that the device's media capture device(s) such as camera or microphone be used instead of requesting a file input.</p> </div> +</div> +<h3 id="multiple">multiple</h3> +<div class="section-content"><p>When the <a href="../../attributes/multiple"><code>multiple</code></a> Boolean attribute is specified, the file input allows the user to select more than one file.</p></div> +<h2 id="non-standard_attributes">Non-standard attributes</h2> +<div class="section-content"><p>In addition to the attributes listed above, the following non-standard attributes are available on some browsers. You should try to avoid using them when possible, since doing so will limit the ability of your code to function in browsers that don't implement them.</p></div> +<h3 id="webkitdirectory"><code>webkitdirectory</code></h3> +<div class="section-content"> +<p>The Boolean <code>webkitdirectory</code> attribute, if present, indicates that only directories should be available to be selected by the user in the file picker interface. See <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory"><code>HTMLInputElement.webkitdirectory</code></a> for additional details and examples.</p> <p>Though originally implemented only for WebKit-based browsers, <code>webkitdirectory</code> is also usable in Microsoft Edge as well as Firefox 50 and later. However, even though it has relatively broad support, it is still not standard and should not be used unless you have no alternative.</p> +</div> +<h2 id="unique_file_type_specifiers">Unique file type specifiers</h2> +<div class="section-content"> +<p>A <strong>unique file type specifier</strong> is a string that describes a type of file that may be selected by the user in an <a href="../input"><code><input></code></a> element of type <code>file</code>. Each unique file type specifier may take one of the following forms:</p> <ul> <li>A valid case-insensitive filename extension, starting with a period (".") character. For example: <code>.jpg</code>, <code>.pdf</code>, or <code>.doc</code>.</li> <li>A valid MIME type string, with no extensions.</li> <li>The string <code>audio/*</code> meaning "any audio file".</li> <li>The string <code>video/*</code> meaning "any video file".</li> <li>The string <code>image/*</code> meaning "any image file".</li> </ul> <p>The <code>accept</code> attribute takes a string containing one or more of these unique file type specifiers as its value, separated by commas. For example, a file picker that needs content that can be presented as an image, including both standard image formats and PDF files, might look like this:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="vaXAnYa80YDd/ePiItp1UmN0zsKPqN0izC31G0hsyIg=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> <span class="token attr-name">accept</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>image/*,.pdf<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> +</pre> +</div> +</div> +<h2 id="using_file_inputs">Using file inputs</h2> + +<h3 id="a_basic_example">A basic example</h3> +<div class="section-content"> +<div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="F/T1yJHvhAVwkARDAgYCgjkZ4KzGemRGO90oG0vofHE=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>form</span> <span class="token attr-name">method</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>post<span class="token punctuation">"</span></span> <span class="token attr-name">enctype</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>multipart/form-data<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span> <span class="token attr-name">for</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Choose file to upload<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> <span class="token attr-name">multiple</span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span><span class="token punctuation">></span></span>Submit<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>form</span><span class="token punctuation">></span></span> +</pre> +</div> <p>This produces the following output:</p> +<div class="code-example" id="sect3"> + +<iframe class="sample-code-frame" title="A basic example sample" id="frame_a_basic_example" width="650" height="90" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/input/file/runner.html?id=a_basic_example" loading="lazy"></iframe> +</div> <div class="notecard note" id="sect4"> <p><strong>Note:</strong> You can find this example on GitHub too — see the <a href="https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/simple-file.html" target="_blank">source code</a>, and also <a href="https://mdn.github.io/learning-area/html/forms/file-examples/simple-file.html" target="_blank">see it running live</a>.</p> </div> <p>Regardless of the user's device or operating system, the file input provides a button that opens up a file picker dialog that allows the user to choose a file.</p> <p>Including the <a href="#multiple"><code>multiple</code></a> attribute, as shown above, specifies that multiple files can be chosen at once. The user can choose multiple files from the file picker in any way that their chosen platform allows (e.g. by holding down <kbd>Shift</kbd> or <kbd>Control</kbd> and then clicking). If you only want the user to choose a single file per <code><input></code>, omit the <code>multiple</code> attribute.</p> +</div> +<h3 id="getting_information_on_selected_files">Getting information on selected files</h3> +<div class="section-content"> +<p>The selected files' are returned by the element's <code>HTMLInputElement.files</code> property, which is a <a href="https://developer.mozilla.org/en-US/docs/Web/API/FileList"><code>FileList</code></a> object containing a list of <a href="https://developer.mozilla.org/en-US/docs/Web/API/File"><code>File</code></a> objects. The <code>FileList</code> behaves like an array, so you can check its <code>length</code> property to get the number of selected files.</p> <p>Each <code>File</code> object contains the following information:</p> <dl> <dt id="name"><a href="#name"><code>name</code></a></dt> <dd> <p>The file's name.</p> </dd> <dt id="lastmodified"><a href="#lastmodified"><code>lastModified</code></a></dt> <dd> <p>A number specifying the date and time at which the file was last modified, in milliseconds since the UNIX epoch (January 1, 1970 at midnight).</p> </dd> <dt id="lastmodifieddate"> +<a href="#lastmodifieddate"><code>lastModifiedDate</code></a> <abbr class="icon icon-deprecated" title="Deprecated. Not for use in new websites."> <span class="visually-hidden">Deprecated</span> </abbr> +</dt> <dd> <p>A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date"><code>Date</code></a> object representing the date and time at which the file was last modified. <em>This is deprecated and should not be used. Use <code>lastModified</code> instead.</em></p> </dd> <dt id="size"><a href="#size"><code>size</code></a></dt> <dd> <p>The size of the file in bytes.</p> </dd> <dt id="type"><a href="#type"><code>type</code></a></dt> <dd> <p>The file's <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME type</a>.</p> </dd> <dt id="webkitrelativepath"> +<a href="#webkitrelativepath"><code>webkitRelativePath</code></a> <abbr class="icon icon-nonstandard" title="Non-standard. Check cross-browser support before using."> <span class="visually-hidden">Non-standard</span> </abbr> +</dt> <dd> <p>A string specifying the file's path relative to the base directory selected in a directory picker (that is, a <code>file</code> picker in which the <a href="#webkitdirectory"><code>webkitdirectory</code></a> attribute is set). <em>This is non-standard and should be used with caution.</em></p> </dd> </dl> <div class="notecard note" id="sect5"> <p><strong>Note:</strong> You can set as well as get the value of <code>HTMLInputElement.files</code> in all modern browsers; this was most recently added to Firefox, in version 57 (see <a href="https://bugzil.la/1384030" target="_blank">Firefox bug 1384030</a>).</p> </div> +</div> +<h3 id="limiting_accepted_file_types">Limiting accepted file types</h3> +<div class="section-content"> +<p>Often you won't want the user to be able to pick any arbitrary type of file; instead, you often want them to select files of a specific type or types. For example, if your file input lets users upload a profile picture, you probably want them to select web-compatible image formats, such as <a href="https://developer.mozilla.org/en-US/docs/Glossary/JPEG">JPEG</a> or <a href="https://developer.mozilla.org/en-US/docs/Glossary/PNG">PNG</a>.</p> <p>Acceptable file types can be specified with the <a href="#accept"><code>accept</code></a> attribute, which takes a comma-separated list of allowed file extensions or MIME types. Some examples:</p> <ul> <li> +<code>accept="image/png"</code> or <code>accept=".png"</code> — Accepts PNG files.</li> <li> +<code>accept="image/png, image/jpeg"</code> or <code>accept=".png, .jpg, .jpeg"</code> — Accept PNG or JPEG files.</li> <li> +<code>accept="image/*"</code> — Accept any file with an <code>image/*</code> MIME type. (Many mobile devices also let the user take a picture with the camera when this is used.)</li> <li> +<code>accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"</code> — accept anything that smells like an MS Word document.</li> </ul> <p>Let's look at a more complete example:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="sO1n56AipdPykkyYIzuTKOBrH9jWxWeWOgHs6OXK758=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>form</span> <span class="token attr-name">method</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>post<span class="token punctuation">"</span></span> <span class="token attr-name">enctype</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>multipart/form-data<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span> <span class="token attr-name">for</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>profile_pic<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Choose file to upload<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> + <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>profile_pic<span class="token punctuation">"</span></span> + <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>profile_pic<span class="token punctuation">"</span></span> + <span class="token attr-name">accept</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>.jpg, .jpeg, .png<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span><span class="token punctuation">></span></span>Submit<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>form</span><span class="token punctuation">></span></span> +</pre> +</div> <p>This produces a similar-looking output to the previous example:</p> +<div class="code-example" id="sect6"> + +<iframe class="sample-code-frame" title="Limiting accepted file types sample" id="frame_limiting_accepted_file_types" width="650" height="90" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/input/file/runner.html?id=limiting_accepted_file_types" loading="lazy"></iframe> +</div> <div class="notecard note" id="sect7"> <p><strong>Note:</strong> You can find this example on GitHub too — see the <a href="https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/file-with-accept.html" target="_blank">source code</a>, and also <a href="https://mdn.github.io/learning-area/html/forms/file-examples/file-with-accept.html" target="_blank">see it running live</a>.</p> </div> <p>It may look similar, but if you try selecting a file with this input, you'll see that the file picker only lets you select the file types specified in the <code>accept</code> value (the exact interface differs across browsers and operating systems).</p> <p>The <code>accept</code> attribute doesn't validate the types of the selected files; it provides hints for browsers to guide users towards selecting the correct file types. It is still possible (in most cases) for users to toggle an option in the file chooser that makes it possible to override this and select any file they wish, and then choose incorrect file types.</p> <p>Because of this, you should make sure that the <code>accept</code> attribute is backed up by appropriate server-side validation.</p> +</div> +<h3 id="notes">Notes</h3> +<div class="section-content"><ol> <li>You cannot set the value of a file picker from a script — doing something like the following has no effect: <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="C2IWJtaJFrSKmhNfIt5zmGky5v1XzWtbwUM3dKsnJs4=" data-language="js"><span class="token keyword">const</span> input <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"input[type=file]"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +input<span class="token punctuation">.</span>value <span class="token operator">=</span> <span class="token string">"foo"</span><span class="token punctuation">;</span> +</pre> +</div> </li> <li>When a file is chosen using an <code><input type="file"></code>, the real path to the source file is not shown in the input's <code>value</code> attribute for obvious security reasons. Instead, the filename is shown, with <code>C:\fakepath\</code> prepended to it. There are some historical reasons for this quirk, but it is supported across all modern browsers, and in fact is <a href="https://html.spec.whatwg.org/multipage/forms.html#fakepath-srsly" target="_blank">defined in the spec</a>.</li> </ol></div> +<h2 id="examples">Examples</h2> +<div class="section-content"> +<p>In this example, we'll present a slightly more advanced file chooser that takes advantage of the file information available in the <code>HTMLInputElement.files</code> property, as well as showing off a few clever tricks.</p> <div class="notecard note" id="sect8"> <p><strong>Note:</strong> You can see the complete source code for this example on GitHub — <a href="https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/file-example.html" target="_blank">file-example.html</a> (<a href="https://mdn.github.io/learning-area/html/forms/file-examples/file-example.html" target="_blank">see it live also</a>). We won't explain the CSS; the JavaScript is the main focus.</p> </div> <p>First of all, let's look at the HTML:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="oEcisEfXc6ZaS41hRYzjYjlNPxWuyfPFT5wbwqL2Yb0=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>form</span> <span class="token attr-name">method</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>post<span class="token punctuation">"</span></span> <span class="token attr-name">enctype</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>multipart/form-data<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>label</span> <span class="token attr-name">for</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>image_uploads<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Choose images to upload (PNG, JPG)<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>label</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>input</span> + <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>file<span class="token punctuation">"</span></span> + <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>image_uploads<span class="token punctuation">"</span></span> + <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>image_uploads<span class="token punctuation">"</span></span> + <span class="token attr-name">accept</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>.jpg, .jpeg, .png<span class="token punctuation">"</span></span> + <span class="token attr-name">multiple</span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>preview<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>No files currently selected for upload<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>button</span><span class="token punctuation">></span></span>Submit<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>button</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>form</span><span class="token punctuation">></span></span> +</pre> +</div> <p>This is similar to what we've seen before — nothing special to comment on.</p> <p>Next, let's walk through the JavaScript.</p> <p>In the first lines of script, we get references to the form input itself, and the <a href="../div"><code><div></code></a> element with the class of <code>.preview</code>. Next, we hide the <a href="../input"><code><input></code></a> element — we do this because file inputs tend to be ugly, difficult to style, and inconsistent in their design across browsers. You can activate the <code>input</code> element by clicking its <a href="../label"><code><label></code></a>, so it is better to visually hide the <code>input</code> and style the label like a button, so the user will know to interact with it if they want to upload files.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="RBStzvLblkuoj2jexlo5CjpTqNTqsjXonwEujy6eLxk=" data-language="js"><span class="token keyword">const</span> input <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"input"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> preview <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">".preview"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +input<span class="token punctuation">.</span>style<span class="token punctuation">.</span>opacity <span class="token operator">=</span> <span class="token number">0</span><span class="token punctuation">;</span> +</pre> +</div> <div class="notecard note" id="sect9"> <p><strong>Note:</strong> <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/opacity"><code>opacity</code></a> is used to hide the file input instead of <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/visibility"><code>visibility: hidden</code></a> or <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/display"><code>display: none</code></a>, because assistive technology interprets the latter two styles to mean the file input isn't interactive.</p> </div> <p>Next, we add an <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener">event listener</a> to the input to listen for changes to its selected value (in this case, when files are selected). The event listener invokes our custom <code>updateImageDisplay()</code> function.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="JmnTxpRvekMWTk0cBbW7tjXC1ubwsp0Cj7o7zchAn+A=" data-language="js">input<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"change"</span><span class="token punctuation">,</span> updateImageDisplay<span class="token punctuation">)</span><span class="token punctuation">;</span> +</pre> +</div> <p>Whenever the <code>updateImageDisplay()</code> function is invoked, we:</p> <ul> <li>Use a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/while"><code>while</code></a> loop to empty the previous contents of the preview <code><div></code>.</li> <li>Grab the <a href="https://developer.mozilla.org/en-US/docs/Web/API/FileList"><code>FileList</code></a> object that contains the information on all the selected files, and store it in a variable called <code>curFiles</code>.</li> <li>Check to see if no files were selected, by checking if <code>curFiles.length</code> is equal to 0. If so, print a message into the preview <code><div></code> stating that no files have been selected.</li> <li>If files <em>have</em> been selected, we loop through each one, printing information about it into the preview <code><div></code>. Things to note here:</li> <li>We use the custom <code>validFileType()</code> function to check whether the file is of the correct type (e.g. the image types specified in the <code>accept</code> attribute).</li> <li>If it is, we: <ul> <li>Print out its name and file size into a list item inside the previous <code><div></code> (obtained from <code>file.name</code> and <code>file.size</code>). The custom <code>returnFileSize()</code> function returns a nicely-formatted version of the size in bytes/KB/MB (by default the browser reports the size in absolute bytes).</li> <li>Generate a thumbnail preview of the image by calling <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static"><code>URL.createObjectURL(curFiles[i])</code></a>. Then, insert the image into the list item too by creating a new <a href="../img"><code><img></code></a> and setting its <a href="../img#src"><code>src</code></a> to the thumbnail.</li> </ul> </li> <li>If the file type is invalid, we display a message inside a list item telling the user that they need to select a different file type.</li> </ul> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="4x65Bllp3JsG007iyxquHFsqAYgILx3nb0GmzTEFpeY=" data-language="js"><span class="token keyword">function</span> <span class="token function">updateImageDisplay</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">while</span> <span class="token punctuation">(</span>preview<span class="token punctuation">.</span>firstChild<span class="token punctuation">)</span> <span class="token punctuation">{</span> + preview<span class="token punctuation">.</span><span class="token function">removeChild</span><span class="token punctuation">(</span>preview<span class="token punctuation">.</span>firstChild<span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> + + <span class="token keyword">const</span> curFiles <span class="token operator">=</span> input<span class="token punctuation">.</span>files<span class="token punctuation">;</span> + <span class="token keyword">if</span> <span class="token punctuation">(</span>curFiles<span class="token punctuation">.</span>length <span class="token operator">===</span> <span class="token number">0</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">const</span> para <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + para<span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token string">"No files currently selected for upload"</span><span class="token punctuation">;</span> + preview<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>para<span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span> + <span class="token keyword">const</span> list <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"ol"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + preview<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>list<span class="token punctuation">)</span><span class="token punctuation">;</span> + + <span class="token keyword">for</span> <span class="token punctuation">(</span><span class="token keyword">const</span> file <span class="token keyword">of</span> curFiles<span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">const</span> listItem <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"li"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token keyword">const</span> para <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token function">validFileType</span><span class="token punctuation">(</span>file<span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + para<span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">File name </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>file<span class="token punctuation">.</span>name<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">, file size </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token function">returnFileSize</span><span class="token punctuation">(</span> + file<span class="token punctuation">.</span>size<span class="token punctuation">,</span> + <span class="token punctuation">)</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">.</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">;</span> + <span class="token keyword">const</span> image <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"img"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + image<span class="token punctuation">.</span>src <span class="token operator">=</span> <span class="token constant">URL</span><span class="token punctuation">.</span><span class="token function">createObjectURL</span><span class="token punctuation">(</span>file<span class="token punctuation">)</span><span class="token punctuation">;</span> + + listItem<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>image<span class="token punctuation">)</span><span class="token punctuation">;</span> + listItem<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>para<span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span> + para<span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">File name </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>file<span class="token punctuation">.</span>name<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">: Not a valid file type. Update your selection.</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">;</span> + listItem<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>para<span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> + + list<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>listItem<span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> + <span class="token punctuation">}</span> +<span class="token punctuation">}</span> +</pre> +</div> <p>The custom <code>validFileType()</code> function takes a <a href="https://developer.mozilla.org/en-US/docs/Web/API/File"><code>File</code></a> object as a parameter, then uses <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes"><code>Array.prototype.includes()</code></a> to check if any value in the <code>fileTypes</code> matches the file's <code>type</code> property. If a match is found, the function returns <code>true</code>. If no match is found, it returns <code>false</code>.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="Zm3sKYd4OUmReiVgNSeQuIvDJBZOl0FjzXkD8flZp9A=" data-language="js"><span class="token comment">// https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types</span> +<span class="token keyword">const</span> fileTypes <span class="token operator">=</span> <span class="token punctuation">[</span> + <span class="token string">"image/apng"</span><span class="token punctuation">,</span> + <span class="token string">"image/bmp"</span><span class="token punctuation">,</span> + <span class="token string">"image/gif"</span><span class="token punctuation">,</span> + <span class="token string">"image/jpeg"</span><span class="token punctuation">,</span> + <span class="token string">"image/pjpeg"</span><span class="token punctuation">,</span> + <span class="token string">"image/png"</span><span class="token punctuation">,</span> + <span class="token string">"image/svg+xml"</span><span class="token punctuation">,</span> + <span class="token string">"image/tiff"</span><span class="token punctuation">,</span> + <span class="token string">"image/webp"</span><span class="token punctuation">,</span> + <span class="token string">"image/x-icon"</span><span class="token punctuation">,</span> +<span class="token punctuation">]</span><span class="token punctuation">;</span> + +<span class="token keyword">function</span> <span class="token function">validFileType</span><span class="token punctuation">(</span><span class="token parameter">file</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">return</span> fileTypes<span class="token punctuation">.</span><span class="token function">includes</span><span class="token punctuation">(</span>file<span class="token punctuation">.</span>type<span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span> +</pre> +</div> <p>The <code>returnFileSize()</code> function takes a number (of bytes, taken from the current file's <code>size</code> property), and turns it into a nicely formatted size in bytes/KB/MB.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="7MUk5n5cUKa8RRBaIju6wnDAgdMDSdKlbaTVhmuKX2I=" data-language="js"><span class="token keyword">function</span> <span class="token function">returnFileSize</span><span class="token punctuation">(</span><span class="token parameter">number</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">if</span> <span class="token punctuation">(</span>number <span class="token operator"><</span> <span class="token number">1024</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">return</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>number<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> bytes</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token keyword">if</span> <span class="token punctuation">(</span>number <span class="token operator">>=</span> <span class="token number">1024</span> <span class="token operator">&&</span> number <span class="token operator"><</span> <span class="token number">1048576</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">return</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token punctuation">(</span>number <span class="token operator">/</span> <span class="token number">1024</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">toFixed</span><span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> KB</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token keyword">if</span> <span class="token punctuation">(</span>number <span class="token operator">>=</span> <span class="token number">1048576</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token keyword">return</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token punctuation">(</span>number <span class="token operator">/</span> <span class="token number">1048576</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">toFixed</span><span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string"> MB</span><span class="token template-punctuation string">`</span></span><span class="token punctuation">;</span> + <span class="token punctuation">}</span> +<span class="token punctuation">}</span> +</pre> +</div> <p>The example looks like this; have a play:</p> +<div class="code-example" id="sect10"> + +<iframe class="sample-code-frame" title="Examples sample" id="frame_examples" width="100%" height="200" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/input/file/runner.html?id=examples" loading="lazy"></iframe> +</div> +</div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <td><strong><a href="#value">Value</a></strong></td> <td> A string representing the path to the selected file. </td> </tr> <tr> <td><strong>Events</strong></td> <td> <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event"><code>change</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event"><code>input</code></a> </td> </tr> <tr> <td><strong>Supported common attributes</strong></td> <td><a href="../input#required"><code>required</code></a></td> </tr> <tr> <td><strong>Additional Attributes</strong></td> <td> <a href="#accept" aria-current="page"><code>accept</code></a>, <a href="#capture" aria-current="page"><code>capture</code></a>, <a href="#multiple" aria-current="page"><code>multiple</code></a> </td> </tr> <tr> <td><strong>IDL attributes</strong></td> <td> +<code>files</code> and <code>value</code> +</td> </tr> <tr> <td><strong>DOM interface</strong></td> <td> <p><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement"><code>HTMLInputElement</code></a></p> </td> </tr> <tr> <td><strong>Methods</strong></td> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select"><code>select()</code></a></td> </tr> <tr> <td><strong>Implicit ARIA Role</strong></td> <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" target="_blank"><code>no corresponding role</code></a></td> </tr> </tbody> </table></div></figure></div> +<h2 id="specifications">Specifications</h2> +<div class="_table"><table class="standard-table"> +<thead><tr><th scope="col">Specification</th></tr></thead> +<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/input.html#file-upload-state-(type=file)">HTML Standard <br><small># file-upload-state-(type=file)</small></a></td></tr></tbody> +</table></div> +<h2 id="browser_compatibility">Browser compatibility</h2> +<div class="_table"><table> +<thead> +<tr id="bct-browser-type"> +<th></th> +<th colspan="6">Desktop</th> +<th colspan="6">Mobile</th> +</tr> +<tr id="bct-browsers"> +<th></th> +<th>Chrome</th> +<th>Edge</th> +<th>Firefox</th> +<th>Internet Explorer</th> +<th>Opera</th> +<th>Safari</th> +<th>WebView Android</th> +<th>Chrome Android</th> +<th>Firefox for Android</th> +<th>Opera Android</th> +<th>Safari on IOS</th> +<th>Samsung Internet</th> +</tr> +</thead> +<tbody><tr> +<th><code>file</code></th> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes"><details><summary>1</summary>You can set as well as get the value of <code>HTMLInputElement.files</code> in all modern browsers; this was most recently added to Firefox, in version 57 (see <a href="https://bugzil.la/1384030">bug 1384030</a>).</details></td> +<td class="bc-supports-yes">Yes</td> +<td class="bc-supports-yes">11</td> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">18</td> +<td class="bc-supports-yes">4</td> +<td class="bc-supports-yes">11</td> +<td class="bc-supports-yes">1</td> +<td class="bc-supports-yes">1.0</td> +</tr></tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/API/File_API/Using_files_from_web_applications">Using files from web applications</a> — contains a number of other useful examples related to <code><input type="file"></code> and the <a href="https://developer.mozilla.org/en-US/docs/Web/API/File">File API</a>.</li> <li><a href="https://developer.mozilla.org/en-US/docs/Learn/Forms/Property_compatibility_table_for_form_controls">Compatibility of CSS properties</a></li> </ul></div><div class="_attribution"> + <p class="_attribution-p"> + © 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br> + <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file</a> + </p> +</div> |