The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

File Input

Gitea

A form input that enables users to select one or more files from their local device for upload.

Usage

The File Input component uses the native HTML input with type="file" under the hood but adds visual styling to match other I80 components.

Browser inconsistency

Because the File Input is based on the native HTML input, the content and visual appearance may vary slightly across browsers.

Examples of file input states rendered in different web browsers

Truncation

Truncation is built into the native component and uses the width of the container to determine when the text gets truncated. It is not based on a character limit.

Multiple files

Multiple files can be added at once when the multiple attribute is enabled in code. When more than one file is selected, the text will change to show the number of files you’ve selected, e.g., “2 files”. The exact language used may differ between browsers.

Several files selected in a File Input

How to use this component

<i80-file-input> uses the native HTML input with type="file" under the hood but adds visual styling to match the other i80 components.

There are two ways to use it:

  • the field: give the element a label attribute and it renders the <input type="file"> control, with label, helper text, and error messaging (in a wrapping container).
  • the base control: leave the label out and write your own <input type="file"> inside the element, which is kept as it is.

We recommend using the field as it provides built-in accessibility functionality. Use the base control if you need to achieve custom layouts or for special use cases not covered by the field.

The field

<i80-file-input label="Upload a file" name="demo-profile-photo"></i80-file-input>

Helper text

You can add extra information to the field using the helper-text attribute. When helper text is added, an aria-describedby attribute is automatically added to the input control, associating it with the automatically generated ID of the helper text element.

<i80-file-input label="Upload a file" helper-text="File size should be a maximum of 2 MB." name="demo-profile-photo"></i80-file-input>

Required vs. optional

Use the required and optional attributes to add a visual indication that the field is "required" or "optional".

<i80-file-input label="Upload a file" helper-text="File size should be a maximum of 2 MB." name="demo-profile-photo" required></i80-file-input>
<i80-file-input label="Upload a file" helper-text="File size should be a maximum of 2 MB." name="demo-profile-photo" optional></i80-file-input>

Validation

To indicate a field is invalid, set the error attribute to the message: it shows the error and marks the control invalid.

<i80-file-input label="Upload a file" name="demo-profile-photo" error="The provided file format is not valid."></i80-file-input>

Custom control ID

In this case, all the internal references (id/for/aria-describedby) between the different parts of the field will still be automatically generated but will use the custom ID provided.

To use a custom ID value instead of the automatically generated one, write the <input type="file"> yourself inside the element, carrying that id.

<i80-file-input label="Upload a file">
  <input type="file" name="demo-profile-photo" id="my-control">
</i80-file-input>

Additional aria-describedby

Set aria-describedby on the element to connect one or more extra elements describing the field to the control. Those ID values are merged with the ones the element generates for the helper text and the error message.

Only PNG and SVG files are accepted.

<p id="my-extra-element-ID">Only PNG and SVG files are accepted.</p>
<i80-file-input label="Upload a file" name="demo-profile-photo" aria-describedby="my-extra-element-ID"></i80-file-input>

HTML native attributes

The element passes name, accept, multiple, capture and form on to the <input type="file"> it creates, so you can add specific native behaviors that are not exposed directly. For anything else, write the <input> yourself inside the element and it is kept as it is, with all of its attributes.

<i80-file-input label="Upload a file" name="demo-profile-photo" accept="image/png,image/svg+xml" multiple required></i80-file-input>

The base control

The base control is intended for rare cases where the field can’t be used and a custom implementation is needed. Most of the details for the field also apply here, but see the Attributes for more details.

<i80-file-input>
  <input type="file" name="demo-profile-photo" accept="image/png,image/svg+xml" aria-label="Upload a file" required>
</i80-file-input>

Attributes

<i80-file-input> renders this component. Everything it understands:

Attribute Values Default Notes
label, helper-text, error, invalid, required, optional, disabled As Text Input.
name, accept, multiple, capture, form Passed to the created <input type="file">.
width CSS length
aria-describedby id list Merged with the helper text and error ids the element links.
files property The chosen FileList; value is the first file's path, as on a native input.

The tag keeps any native element you write inside it, so a server-rendered form, link or button works as it is. See Web Components for loading i80.js and the reference for these examples running.

Anatomy

Anatomy of File Input

Element Usage
Label Required
Indicator Optional
Helper text Optional
Button Required
File status Update triggered by system
Error message Triggered by system

States

Example of File Input states

Accessibility consideration

Because disabled states completely remove the interactive function of an element, it can be challenging for a user to understand why it has been disabled and/or why they cannot interact with that element. For this reason, we recommend using disabled fields sparingly and with intention. Instead, consider using methods like enabling or hiding the element. Read more about when to enable vs hide.

Conformance rating

Conformant

When used as recommended, there should not be any WCAG conformance issues with this component.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

  • 1.3.1 Info and Relationships (Level A):
    Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
  • 1.3.2 Meaningful Sequence (Level A):
    When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined.
  • 1.3.4 Orientation (Level AA):
    Content does not restrict its view and operation to a single display orientation, such as portrait or landscape.
  • 1.3.5 Identify Input Purpose (Level AA):
    The purpose of each input field collecting information about the user can be programmatically determined when the input field serves a purpose identified in the Input Purposes for User Interface Components section; and the content is implemented using technologies with support for identifying the expected meaning for form input data.
  • 1.4.1 Use of Color (Level A):
    Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
  • 1.4.10 Reflow (Level AA):
    Content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions.
  • 1.4.11 Non-text Contrast (Level AA):
    The visual presentation of the following have a contrast ratio of at least 3:1 against adjacent color(s): user interface components; graphical objects.
  • 1.4.12 Text Spacing (Level AA):
    No loss of content or functionality occurs by setting all of the following and by changing no other style property: line height set to 1.5; spacing following paragraphs set to at least 2x the font size; letter-spacing set at least 0.12x of the font size, word spacing set to at least 0.16 times the font size.
  • 1.4.3 Minimum Contrast (Level AA):
    The visual presentation of text and images of text has a contrast ratio of at least 4.5:1
  • 1.4.4 Resize Text (Level AA):
    Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.
  • 2.4.6 Headings and Labels (Level AA):
    Headings and labels describe topic or purpose.
  • 2.4.7 Focus Visible (Level AA):
    Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.
  • 3.2.1 On Focus (Level A):
    When any user interface component receives focus, it does not initiate a change of context.
  • 3.2.2 On Input (Level A):
    Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.
  • 3.2.4 Consistent Identification (Level AA):
    Components that have the same functionality within a set of Web pages are identified consistently.
  • 3.3.1 Error Identification (Level A):
    If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.
  • 3.3.2 Labels or Instructions (Level A):
    Labels or instructions are provided when content requires user input.
  • 4.1.2 Name, Role, Value (Level A):
    For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

0.1.0

Første i80-version (fork af upstream, se core/UPSTREAM.md).

On this page: