About Project Overview Contributing Getting Started Installation Usage Themes Customizing Frameworks React Vue Angular GitHub Light Dark System

File Upload

<terra-file-upload> | TerraFileUpload
Since 1.0 stable

File upload fields allow visitors to attach one or multiple files to be submitted with a form.

File Upload

File upload fields allow visitors to attach one or multiple files to be submitted with a form.

Examples

Basic File Upload 

<terra-file-upload label="Upload"></terra-file-upload>

With Help Text 

<terra-file-upload
  label="Upload"
  help-text="Accepts all image formats."></terra-file-upload>

Multiple Files 

<terra-file-upload
  label="Upload"
  multiple
  help-text="Accepts all image formats."></terra-file-upload>

With File Type Restrictions 

<terra-file-upload
  label="Upload Images"
  accept="image/*"
  help-text="Accepts all image formats."></terra-file-upload>

Required Field 

<terra-file-upload
  label="Upload"
  required
  help-text="Accepts all image formats."></terra-file-upload>

Disabled State 

<terra-file-upload
  label="Upload"
  disabled
  help-text="Accepts all image formats."></terra-file-upload>

With Maximum File Size 

<terra-file-upload
  label="Upload"
  max-file-size="5242880"
  help-text="Maximum file size: 5MB. Accepts all image formats."></terra-file-upload>

With Maximum Number of Files 

<terra-file-upload
  label="Upload"
  multiple
  max-files="3"
  help-text="Maximum 3 files. Accepts all image formats."></terra-file-upload>

Form Integration


Submit 
<form id="upload-form">
  <terra-file-upload
    name="files"
    label="Upload"
    required
    multiple
    accept="image/*"
    help-text="Accepts all image formats."></terra-file-upload>
  <br>
  <terra-button type="submit">Submit</terra-button>
</form>

Usage

Use file upload fields when files are required as part of a form submission for an application, contest entry, etc. The field can support single or multiple file uploads with drag and drop, or by clicking/tapping to open a native file browser. Using one file per field is recommended when each file has a distinct purpose, to make it clear for NASA team members who are receiving and reviewing form submissions.

Best Practices

  • Labels: Always include a clear and concise label for each file upload field.
  • Help text: Use the help-text attribute to clearly explain which file formats are allowed and any size or quantity restrictions.
  • File types: Unless totally necessary, it is recommended to accept multiple file formats to avoid unnecessary software requirements for users.
  • File size: Be careful when requesting large files, as some visitors might have limited connectivity or data plans. Use the max-file-size attribute to set reasonable limits.
  • Multiple files: Use the multiple attribute when users need to upload several related files. Consider using the max-files attribute to limit the number of files.
  • Single vs. multiple: Using one file per field is recommended when each file has a distinct purpose, to make it clear for NASA team members who are receiving and reviewing form submissions.
  • Progressive enhancement: This field should be used as a progressive enhancement of the standard HTML field. The browser-default input field should be the fallback if any issues occur with this custom field.

Accessibility

  • The terra-file-upload component is built with accessibility in mind, using native <input type="file"> under the hood.
  • Labels are properly associated with the file input using the for attribute.
  • Required fields are indicated with an asterisk.
  • Help text is provided below the file upload field for additional context.
  • The component supports keyboard navigation (Tab to focus, Enter/Space to activate).
  • Focus states are clearly visible with a focus ring.
  • Screen readers are properly notified of file selections.

[component-metadata:terra-file-upload]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/file-upload/file-upload.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/file-upload/file-upload.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/file-upload/file-upload.js';

To import this component as a React component:

import TerraFileUpload from '@nasa-terra/components/dist/react/file-upload';

Slots

Name Description
(default) Custom content to display inside the drop zone.

Learn more about using slots.

Properties

Name Description Reflects Type Default
label The file upload’s label. string 'Upload'
helpText
help-text 		The file upload’s help text. string ''
name The name of the file input, submitted as a name/value pair with form data. string ''
multiple Allows multiple files to be selected. boolean false
disabled Disables the file upload. boolean false
required Makes the file upload a required field. boolean false
accept Accepted file types (e.g., “image/*”, ”.pdf”, “image/png,image/jpeg”). string ''
maxFileSize
max-file-size 		Maximum file size in bytes. number | undefined -
maxFiles
max-files 		Maximum number of files allowed when multiple is enabled. number | undefined -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
terra-change onTerraChange Emitted when files are selected or removed. -
terra-focus onTerraFocus Emitted when the control gains focus. -
terra-blur onTerraBlur Emitted when the control loses focus. -

Learn more about events.

Methods

Name Description Arguments
getFiles() Gets the current files. -
clearFiles() Clears all selected files. -

Learn more about methods.

Custom Properties

Name Description Default
--terra-file-upload-* All file upload design tokens from horizon.css are supported.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.
dropzone The drop zone area.
file-input The hidden file input element.
file-list The container for file previews.
file-item Individual file preview item.
file-thumbnail The file thumbnail image.
file-name The file name text.
change-link The “Change files” link.

Learn more about customizing CSS parts.