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>
      class="bx--file-btn bx--btn bx--btn--primary bx--btn--sm"
      tabindex="0">Add file</label>
    <div data-file-container class="bx--file-container"></div>



Getting component class reference

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


// `#my-file` is an element with `[data-file]` attribute

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);


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


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).


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.


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.


.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.


Complete injects checkmark icons into each filename state container.


.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.


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;