Markdown docs
FileUploader
FileUploader allows users to pick one or more files to upload.
FileUploader itself actually does not upload anything to the server.
FileUploader is a composition of a few subcomponents:
- FileUploader
- JavaScript Plugin
- FileUploader
- Fluid Width
- API
- FileUploaderInput
- Selecting Multiple Files at Once
- Maximum File Size (JavaScript)
- Maximum Number of Files in Queue (JavaScript)
- Input Behavior When the Queue is Filled (JavaScript)
- Allowed File Types
- Required Input
- Validation States
- Disabled State
- API
- FileUploaderList
- API
- FileUploaderAttachment
- API
- Composition
JavaScript Plugin
For full functionality, you need to provide Spirit JavaScript:
<script src="node_modules/@lmc-eu/spirit-web/js/cjs/spirit-web.min.js" async></script>Please consult the main README for how to include JavaScript plugins.
Or, feel free to write the controlling script yourself.
👉 Check the component's docs in the web package to see the full documentation and API of the plugin.
FileUploader
This is the main wrapper for the whole composition. It provides proper spacing for its subcomponents (and holds the instance of the FileUploader JS class):
<FileUploader data-spirit-toggle="fileUploader">
<!-- FileUploaderInput -->
<!-- FileUploaderList -->
</FileUploader>Fluid Width
By adding the isFluid attribute, FileUploader can take up all the available horizontal space:
<FileUploader isFluid data-spirit-toggle="fileUploader">
<!-- FileUploaderInput -->
<!-- FileUploaderList -->
</div>API
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| isFluid | bool | false | ✕ | If true, the element spans to the full width of its parent |
On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.
FileUploaderInput
FileUploaderInput is a file picker built around the native HTML file input.
If supported by the device, FileUploaderInput automatically turns on the drag-and-drop functionality.
<FileUploaderInput
helperText="Max file size is 10 MB"
id="example-input"
label="Label"
name="example-input"
/>Selecting Multiple Files at Once
To pick more than one file, just add the multiple attribute that will be transferred to the native HTML input:
<FileUploaderInput
id="example-input"
label="Label"
multiple
/>Maximum File Size (JavaScript)
The maximum size of the uploaded file that is validated by the JavaScript plugin can be adjusted. The default value is 10 MB. To increase the limit for example to 20 MB, add the maxFileSize attribute. The attribute value should be given in bytes:
<FileUploaderInput maxFileSize={ 20000000 } />Maximum Number of Files in Queue (JavaScript)
Limit of the maximum number of uploaded files. The default value is 10, but any value can be set via the maxUploadedFiles attribute:
<FileUploaderInput maxUploadedFiles={ 2 } />Input Behavior When the Queue is Filled (JavaScript)
You can set the input/drop zone to be hidden or disabled when the file queue limit is reached. When you set queueLimitBehavior together with the desired limit for the queue:
Using the queueLimitBehavior attribute together with the desired limit for the queue, you can set the input/drop zone to be hidden or disabled when the file queue limit is reached. Available options are: hide, disable, or none (default).
If you set the value of queueLimitBehavior to disable, the input will be disabled. When you set it to hide, the input disappears completely. After removing a file from the queue, the input is restored.
<FileUploaderInput maxUploadedFiles={ 2 } queueLimitBehavior="hide" />Allowed File Types
Use the accept HTML attribute to restrict what file types can be uploaded. For example, to accept Microsoft Word documents:
<FileUploaderInput
accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"
id="example-input"
label="Label"
/>Required Input
To mark the input as required, simply add the isRequired attribute:
<FileUploaderInput
id="example-input"
isRequired
label="Label"
/>Validation States
Just like any other form component in Spirit, FileUploader implements the Validation state dictionary.
Validation states can be presented either by adding the validationState attribute, or by adding a JS interaction class on the native HTML input when controlled by JavaScript (has-success, has-warning, has-danger).
When validated on server:
<FileUploaderInput
id="example-validation-success"
label="Label"
validationState="success"
validationText="Success validation message"
/>Disabled State
To mark the input as disabled, simply add the isDisabled attribute:
<FileUploaderInput
id="example-input"
isDisabled
label="Label"
/>API
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| accept | string | null | ✕ | Allowed file types |
| dragAndDropText | string | or drag and drop here | ✕ | Text shown in the drop zone if drag-and-drop is enabled on the device |
| helperText | string | null | ✕** | Custom helper text |
| iconName | string | upload | ✕ | Icon used in the drop zone |
| id | string | — | ✔ | Input and label identification |
| isDisabled | bool | false | ✕ | If true, input is disabled |
| isLabelHidden | bool | false | ✕ | If true, label is hidden |
| isRequired | bool | false | ✕ | If true, input is required |
| label | string | null | ✕* | Label text |
| maxFileSize | number | 1000000 | ✕ | The maximum size of the uploaded file in bytes |
| maxUploadedFiles | number | 10 | ✕ | Maximum file upload queue size |
| multiple | void | null | ✕ | If set, multiple files can be selected |
| name | string | null | ✕ | Input name |
| pickAFileText | string | Upload your file | ✕ | Text shown in the drop zone |
| queueLimitBehavior | [hide | disable | none] | none | ✕ | Input behavior when the file queue is filled |
| UNSAFE_helperText | string | null | ✕** | Unescaped custom helper text |
| UNSAFE_label | string | null | ✕* | Unescaped label text (allows HTML) |
| UNSAFE_validationText | [string | string[]] | null | ✕** | Unescaped validation text |
| validationState | Validation dictionary | null | ✕ | Type of validation state |
| validationText | [string | string[]] | null | ✕** | Validation text |
(*) To keep the component accessible, a label is always required. You can use the label for simple text or UNSAFE_label for HTML content. (**) Props with and without UNSAFE_ prefix are mutually exclusive.
On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.
FileUploaderList
FileUploaderList is a simple wrapper which provides an accessible title and the list semantics for the selected files.
👉 When you have more than one file uploader on the page, use the headingId prop to set a unique ID for each list.
<FileUploaderList>
<!-- Attachments, typically inserted by the JavaScript plugin -->
</FileUploaderList>API
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| headingId | string | file-uploader-attachments | ✕ | List and heading identification |
| headingText | string | Attachments | ✕ | List title |
On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.
FileUploaderAttachment
FileUploaderAttachment represents the files to be uploaded. It is expected to be a direct descendant of FileUploaderList, so in the background, it uses <li> as the root element.
Long file names are automatically truncated.
<FileUploaderAttachment fileName="My resume.docx" />FileUploaderAttachment with image preview and edit button:
<FileUploaderAttachment fileName="Profile.jpg" imagePreview="https://...Profile.jpg" onEdit="() => {}" />While you may insert FileUploaderAttachment into your FileUploaderList, in typical use cases it will live inside a <template> tag in the parent FileUploader. The <template> tag must be inserted inside the main wrapper element that has the data-spirit-toggle="fileUploader" attribute. Our JavaScript FileUploader plugin will then pick up the template and apply it on any attachments the user wants to upload. In order to make the template work with image preview, add the generateImagePreview prop to the FileUploaderAttachment inside the <template>.
<FileUploader data-spirit-toggle="fileUploader">
<template data-spirit-snippet="item">
<FileUploaderAttachment />
</template>
<!-- FileUploaderInput -->
<!-- FileUploaderList -->
</FileUploader>With image preview:
<FileUploader data-spirit-toggle="fileUploader">
<template data-spirit-snippet="item">
<FileUploaderAttachment generateImagePreview />
</template>
<!-- FileUploaderInput -->
<!-- FileUploaderList -->
</FileUploader>API
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| editText | string | Edit | ✕ | Edit button text |
| fileName | string | null | ✕ | File name |
| generateImagePreview | bool | false | ✕ | If true and used in the attachment template, the JS plugin will try to show a preview of the image |
| iconName | string | file | ✕ | Icon shown along the file |
| imagePreview | string | null | ✕ | URL or base64 of an image |
| imageObjectFit | [cover | contain] | cover | ✕ | Defines FileUploaderAttachment image fit in container |
| onEdit | func | null | ✕ | Function to trigger on click on edit button |
| removeText | string | Remove | ✕ | Remove button text |
On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.
Composition
This is how all subcomponents build up the complete FileUploader:
<FileUploader data-spirit-toggle="fileUploader">
<template data-spirit-snippet="item">
<FileUploaderAttachment />
</template>
<FileUploaderInput
helperText="Max file size is 10 MB"
id="example-input"
label="Label"
name="example-input"
/>
<FileUploaderList />
</FileUploader>Example