Open UI

File (Explainer)

Overview

The <input type="file"> (or file input) element is a control that provides the user with the ability to select local files.

Background

The file input allows users to upload one or multiple files, which may or may not be part of a form submission.

Currently, this control is the only way access to access a user’s filesystem.

Use Cases

The file input is widely used across the web. Examples include attaching documents to a job or visa application, and uploading multimedia content to cloud storage services.

Non-goals

The file input does not provide a way to programatically invoke access to a user’s filesystem, other than invoking click().

Features

This control invokes a prompt to the user requesting that the user specify one or more files to upload. Once selected, the prompt collapses and input is updated with the selected files.

Risks and Challenges

There are no risks or challenges presented as a part of this proposal.

Prior Art/Examples

Examples can also be found within platforms like GitHub (attaching binaries to a release), along with many government sites.

Design

The file input consists of two parts: a button, and a label. Clicking the button invokes the file selection prompt.

API

Properties and Attributes

Attribute NameTypeDefault ValueDescription
acceptstringEmpty stringOne or more unique file type specifiers describing file types to allow
capturestringnullWhat source to use for capturing image or video data (user or environment)
valueDOMStringEmpty stringA DOMString that represents the path to the selected file(s). If the user selected multiple files, the value represents the first file in the list of files they selected
filesFileListEmpty FileListA FileList listing the chosen files
multiplebooleanfalseA boolean which, if present, indicates that the user may choose more than one file

Methods

SignatureDescription
click(): voidTriggers the system file picker UI to show. Requires user activation.
showPicker(): voidTriggers the system file picker UI to show. Requires user activation.

Events

Event NameDetail TypeBubblesComposedCancellableDispatch Behavior
changenonetruetruefalseFired when the input’s value is commited by the user.
inputnonetruetruefalseFired when the input’s value changes.

Anatomy

Diagram

DOM Structure

<host>
  <slot name="file-selector-button">
    <button part="file-selector-button"></button>
  </slot>
  <slot name="label">
    <span part="label"></span>
  </slot>
</host>

Slots

Slot NameDescriptionFallback Content
file-selector-buttonInvokes the file selection prompt.A button element is provided.
labelIndicates if a file input is waiting for file selection, or if it has selected files.A span element is provided.

CSS Parts

Part NameDescription
file-selector-buttonThe controls button.
labelThe controls label, indicating file selection status.

Behavior

States and Interactions

When the input is invoked, the file selection prompt will limit the user to selecting files that match the accept attribute, and the user will be limited to selecting a single file unless the multiple attribute is true.

When a file are selected, the label updates to show the filename. When set to multiple, the number of selected files is shown instead of a filename.

If a user cancels the prompt (choosing not to select a file), the input shows the default (no selection) state. This also clears any previously selected files.

Drag and drop

Users may also drag and drop files onto the input, where the drop target is the containing element.

Accessibility

The file input should be focusable via keyboard navigation (tab).

Keyboard Navigation and Focus

When no files have been selected, there will be one tap stop for the entire control (resolution).

Form Input

The file input integrates with forms, accepting the required attribute for validation.

Use with Assistive Technology

The openui-file component should appear as a button (ARIA role) along with a label representing the current selection state.

As with other form controls, a label should be used to give context to this control.

Globalization

The positions of the button and label should be reversed for languages written RTL (right-to-left).

Security

The <input type="file"> element doesn’t allow applictions access to the filesystem, and the value is prefixed with a fake path.

Performance

There are no current performance concerns for the file input.

Dependencies

No third party dependencies are required.

Platform Requirements

To implement a custom file input, a developer must create a hidden <input type="file"> element, and call click() or showPicker() on that element to invoke that input’s behaviour.

The Native File System API will allow for implementations of file input controls without the above workaround.

Tooling

No additional tooling is required for the file input.


Resources

Next steps

Some file input implementations list selected files for the user to review, deselect/remove, and possibly rename. There is not specification for this behaviour.