File (Editor's Draft)

File Input Component Specification

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 Name	Type	Default Value	Description
`accept`	`string`	Empty `string`	One or more unique file type specifiers describing file types to allow
`capture`	`string`	`null`	What source to use for capturing image or video data (`user` or `environment`)
`value`	`DOMString`	Empty `string`	A `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
`files`	`FileList`	Empty `FileList`	A `FileList` listing the chosen files
`multiple`	`boolean`	`false`	A `boolean` which, if present, indicates that the user may choose more than one file

Methods

N/A

Events

Event Name	Detail Type	Bubbles	Composed	Cancellable	Dispatch Behavior
`change`	none	`true`	`true`	`false`	Fired when the input's `value` is commited by the user.
`input`	none	`true`	`true`	`false`	Fired when the input's `value` changes.

Anatomy

Diagram

Show slots

DOM Structure

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

Slots

Slot Name	Description	Fallback Content
`file-selector-button`	Invokes the file selection prompt.	A button element is provided.
`label`	Indicates if a file input is waiting for file selection, or if it has selected files.	A label element is provided.

CSS Parts

Part Name	Description
`file-selector-button`	The controls button.
`label`	The 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() 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.