Helsinki Design System
Helsinki Design System
Getting started
Tutorials
Guidelines
Visual assets
Design tokens
Components
OverviewAccordionButtonCardCheckboxDate inputDialogDropdownFieldsetFile inputPrinciplesAccessibilitySecurityUsage and variationsDemos & APIFooterIconKorosLinkLinkboxLoading spinnerLogoNavigationNotificationNumber inputPassword inputPhone inputRadio buttonSearch inputSelection groupSide navigationStatus labelTabsTagText fieldsTime inputToggle buttonTooltip
Patterns
About
Contributing
Resources

File input

DraftAccessible

A file input helps the user to browse and select one or multiple files to be uploaded to the service.

Principles

  • A label should always be provided with a FileInput. It should clearly describe what the user is expected to select.
  • The helper text below the FileInput describes the file requirements to the user. It lists accepted file formats as well as the maximum size of a single file.
    • Note that the helper text is generated automatically from the accept and maxSize properties.
  • The FileInput does not automatically upload files to any server. The user is required to submit the form before the actual upload happens.
  • One FileInput can be configured to accept one or multiple files.
    • Make sure labels of the input indicate the number of expected files to the user.
    • A FileInput allowing multiple files fits well for situations where all the files are related to each other (e.g. multiple photos from the same event).
    • If the user has to upload multiple files that are not related to each other, prefer using multiple file uploads - one for each file.
  • Dragging and dropping files can be allowed by using the dragAndDrop property.
  • The FileInput uses an info text element to inform the user about the status of the component. You can read more about the usage of the info text element in the HDS Form validation pattern documentation page.
  • The FileInput component resolves human-readable file size abbreviations based on a binary system. The file size texts are shown after the selected file name and in maxSize messages if maxSize validation is used.

Accessibility

  • While dragging and dropping files is not considered to be accessible, HDS will always include the default input below the drag and drop area. Clicking the drag and drop area also opens the device-specific file browser.
  • For selecting files, HDS utilises the file browser native to the user's device. While all devices' file browsers do not have the best accessibility features, they are often the most familiar way of selecting files for the user.

Security

As HDS FileInput provides only the front-end solution, remember that you need to take care of the security in your project. Below are some good practices you need to consider. For more detailed checklist, please refer to Helsinki OWASP Application Security Verification Standard.

  • Do not trust the front-end solution to validate the files for you. Validate files on the backend.
    • Verify file type, file size, and name length.
    • HDS FileInput verifies the file size and the file type based on the DOM File object properties. It does not examine the file contents. This validation is not sufficient in the backend since it can be bypassed for example by renaming the file.
  • Always restrict and only allow file types related to the use case.
  • Pay attention to error messages returned from the backend. Do not include information the user does not need, e.g. file paths.
  • If files are uploaded from untrusted sources, make sure files are stored outside of the web root, with limited permissions, preferably with strong validation.
    • Files from untrusted sources should also be scanned by antivirus scanners to prevent the upload of known malicious content.

Usage and variations

File input

In its default form, the HDS FileInput offers a button-like element that opens a file browser native to the user's current device. Selected files are presented in a list below the input and files can be removed from the listing separately.

Only .png and .jpg files. The maximum file size is 1.5 MB.

    React code example:

    {() => {
    const [file, setFile] = React.useState([]);
    console.log('selected file', file);
    return <FileInput
    id="file-input"
    label="Choose a file"
    language="en"
    maxSize={1.5 * 1024 * 1024}
    accept=".png,.jpg"
    onChange={setFile}
    />
    }}

    File input with drag and drop

    If in some cases having the ability to drag and drop files onto the page could help the user, this can be enabled with the dragAndDrop property. Note that the traditional file input is still included below the drag and drop area. Therefore this property does not weaken the accessibility of the component.

    or browse from your device
    Only .png and .jpg files.

      React code example:

      {() => {
      const [files, setFiles] = React.useState([]);
      console.log('selected files', files);
      return <FileInput
      multiple
      dragAndDrop
      id="file-input"
      label="Drag and drop files here"
      language="en"
      accept=".png,.jpg"
      onChange={setFiles}
      />
      }}

      Demos & API

      Core

      Not included in hds-core!

      React

      FileInput in hds-react

      FileInput API