File (Explainer)

OverviewSection titled Overview

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

BackgroundSection titled 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 CasesSection titled Use%20Cases

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-goalsSection titled Non-goals

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

FeaturesSection titled 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 ChallengesSection titled Risks%20and%20Challenges

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

Prior Art/ExamplesSection titled Prior%20Art/Examples

• Ant Design
• Bootstrap
• Carbon
• Evergreen
• KoliBri
• Materialise
• MOJ

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

DesignSection titled Design

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

APISection titled API

Properties and AttributesSection titled Properties%20and%20Attributes

MethodsSection titled Methods

EventsSection titled Events

AnatomySection titled Anatomy

DiagramSection titled Diagram

DOM StructureSection titled DOM%20Structure

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

SlotsSection titled Slots

CSS PartsSection titled CSS%20Parts

BehaviorSection titled Behavior

States and InteractionsSection titled States%20and%20Interactions

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 dropSection titled Drag%20and%20drop

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

AccessibilitySection titled Accessibility

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

Keyboard Navigation and FocusSection titled Keyboard%20Navigation%20and%20Focus

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

Form InputSection titled Form%20Input

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

Use with Assistive TechnologySection titled Use%20with%20Assistive%20Technology

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.

GlobalizationSection titled Globalization

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

SecuritySection titled Security

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

PerformanceSection titled Performance

There are no current performance concerns for the file input.

DependenciesSection titled Dependencies

No third party dependencies are required.

Platform RequirementsSection titled Platform%20Requirements

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.

ToolingSection titled Tooling

No additional tooling is required for the file input.

ResourcesSection titled Resources

• MDN Reference on the current <input type=“file”>
• MDN Reference on the File API
• WHATWG Living Standard on <input type=“file”>

Next stepsSection titled Next%20steps

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