Skip to main content
File uploader allows the user to transfer a file or submit content of their own.

File uploader

Account photo

only .jpg and .png files. 500kb max file size.

Vanilla JS

<div class="bx--form-item">
  <strong class="bx--file--label">Account photo</strong>
  <p class="bx--label-description">only .jpg and .png files. 500kb max file size.</p>
  <div class="bx--file" data-file>
    <label
      for="your-file-importer-id-here"
      class="bx--file-btn bx--btn bx--btn--primary bx--btn--sm"
      role="button"
      tabindex="0">Add file</label>
    <input
      type="file"
      class="bx--file-input"
      id="your-file-importer-id-here"
      data-file-uploader
      data-target="[data-file-container]"
      multiple
    />
    <div data-file-container class="bx--file-container"></div>
  </div>
</div>

Documentation

JavaScript

Getting component class reference

ES2015
import { FileUploader } from 'carbon-components';
With pre-build bundle (carbon-components.min.js)
var FileUploader = CarbonComponents.FileUploader;

Instantiating

// `#my-file` is an element with `[data-file]` attribute
FileUploader.create(document.getElementById('my-file'));

Public Methods

Name Params Description
setState state: String, selectIndex: Number After files are added, call this method to change state of the filenames ('upload', 'complete', 'edit').
release Deletes the instance
Example - Changing the uploading state
// `#my-file` is an element with `[data-file]` attribute
var fileUploaderInstance = FileUploader.create(document.getElementById('my-file'));
// Makes the 2nd file shown as its uploading complete
fileUploaderInstance.setState('complete', 1);

Options

Option Default Selector Description
selectorInit [data-file] Element for initializing instance
selectorInput [input[type="file"].bx--file-input] Input element
selectorContainer [data-file-container] Element for injecting HTML for upload and edit states
selectorCloseButton .bx--file-close Close button for removing filename nodes

Events

Event Name Description
change When files are added to File Uploader, a change event is fired. This also triggers custom events; see eventBeforeDisplayFilesFileuploader and eventAfterDisplayFilesFileuploader`
eventBeforeDeleteFilenameFileuploader Triggered before clicking on close button(s) inside filename node(s).
eventAfterDeleteFilenameFileuploader Triggered after clicking on close button(s) inside filename node(s).

FAQ

Using and understanding File Uploader

When files are added to File Uploader, a change event is fired. The change event triggers a private method to inject HTML into the selectorContainer element displaying all added filenames.

file

Trigger additional states using setState() public method. Additional states are edit, complete and upload.

Edit injects close icons into each filename state container. A click event listener is also added to remove the filename when close button is clicked.

edit

.bx--file__state-container .bx--file-close {
  width: 1rem;
  height: 1rem;
  fill: $text-01;
  cursor: pointer;
}

Upload injects Loading components into each filename state container.

Developers using File Uploader will be able to use JavaScript to inject a Loading component when selected files are actually being uploaded. Users can select a single file or multiple files. By default, any file type is accepted. It's up to the developer and their design team to specify and implement validations for which file types are acceptable.

upload

Complete injects checkmark icons into each filename state container.

complete

.bx--loading {
  width: 2rem;
  height: 2rem;
  margin-right: -7px;
}
.bx--loading__svg {
  stroke: $ui-05;
}

WCAG AA Color Accessibility

File Uploader color contrast ratios are accessible. Since File Uploader (specifically filename elements) low-opacity colors, verifying color ratios with IBM a11y tool may not yield passing results.

However, evaluating resulting background colors as solid colors will pass.

Opacity + UI background color Actual background color Text color WCAG AA Color Ratio Passes 4.5?
#5a6872 at 10% on #ffffff #cedbec #152935 10.70 :white_check_mark:
#5a6872 at 10% on #f5f7fa #c6d5e8 #152935 10.07 :white_check_mark:

Truncating long filenames

By default, filenames are truncated so that any filename that goes beyond 300px will be cutoff.

image

Truncating filenames is enabled through the use of @mixin text-overflow($size).

You can override this behavior with SCSS by giving the @mixin a new width by overriding this @mixin.

// Using mixin, override initial styles in _file-uploader.scss
.bx--file-filename {
  @include text-overflow(768px);
}

You can also use plain CSS by setting a new width.

.bx--file-filename {
  width: 768px;
}