File uploader
only .jpg and .png files. 500kb max file size.
<!--
Copyright IBM Corp. 2016, 2018
This source code is licensed under the Apache-2.0 license found in the
LICENSE file in the root directory of this source tree.
-->
<div class="bx--form-item">
<strong class="bx--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 />
<di data-file-container class="bx--file-container">
</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.
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;
}