Component library
Upload component
Last updated 2 November 2026
Defines an input file field. ( NOTE: This component does not handle file upload process. It only serves as an 'input' field.)
Live demo
<ins-input-file
label="Description Example"
html-description
description="This is a <strong>Description</strong> <i>Example</i>">
</ins-input-file>Attributes
| FIELD ATTRIBUTE | TYPE | DEFAULT | OPTIONS | DESCRIPTION |
|---|---|---|---|---|
| label | string | "" | any | Label shown for the field |
| subtext | string | "" | any | Text shown below the label. This will overwrite the default subtext |
| name | string | file | any | Specify the field name |
| value | array object | "" | [{name: string!, url: string!, size: int, type: sting}] ie. [{name: "sample.jpg", url: "https://docs.prod01-insites.io/assets/images/sample.jpeg", size: 1231, type: "image/jpg"}] | Specify field value |
| placeholder | string | "Drop file here or click to upload" | any | Text display when field is empty |
| disabled | boolean | false | true, false | Disables the field |
| capture | string | "" | any (ie. camera) | Add the attribute 'capture' to the field. Commonly used for device integrations (ie. mobile apps) |
| show-notifications | boolean | true | true, false | Display an alert/notification/error when an event happen to file. (ie. invalid file type, exceeded file size, exceeded max file count, cancelled upload, etc.) |
| has-error | boolean | false | true, false | Defines if the field is invalid / error |
| error-message | string | "" | any | Message shown when field has error |
| required | boolean | false | true, false | Specifies that the field must be filled out before submitting the form |
| file-icon | string | "icon-notepad" | any | CSS class used to for icon display for 'not image' files |
| accepted-files | string | "" | any | Define file types accepted, comma separated to allow 'multiple' types. ie. image/*, application/pdf, .svg, .zip |
| type-label | string | "file" | any | Specify the label for type of file(s) (ie. documents, files, photos, etc.) |
| max-files | number | 1 | integer > 0 | Specify maximum file(s) can be attached |
| max-file-size | number | 10 | integer > 0 | Specify maximum bytes/size (per file) that can be attached |
| show-limit | boolean | true | true, false | Specify if the file restriction limit is shown or hidden |
| max-files-label | string | "Up to" | any | Specify the text label for max file count |
| max-file-size-label | string | "Max file size" | any | Specify the text label for max file size |
| auto-upload | boolean | false | true, false | Automatically upload file(s) to S3 and binds the uploaded URL to the file data as 'upload_url'. NOTE: Only supports upload to the Insites S3 file store. |
| credentials-url | string | "" | any valid URL | API source to get upload credentials. |
| field-type | string | "image" | Insites fields: ["image", "file"] | Insites field type to reference for the credentials. (case sensitive) |
| field-name | string | "" | any | Field name to reference for the credentials. (case sensitive) |
| tooltip | string | "" | - | Displays a tooltip beside the label. Supports HTML Content |
| html-description | boolean | false | true, false | Enables HTML tags in the description |
| description | string | "" | any | Defines the description value |
Events
| EVENT | OBJECT | DESCRIPTION |
|---|---|---|
| insFileAdded | file | Emit file details when a file is successfully accepted/added on the field. |
| insFileRemoved | file | Emit file details when a file is removed from the field. |
| insFileError | file | Emit file details when a file is rejected/invalid. |
Methods
| FUNCTION | PARAMETERS | RETURN | DESCRIPTION |
|---|---|---|---|
| getFilesList | n/a | array object | Return all files on the field |
| getUploadingFiles | n/a | array object | Return all files being uploaded |
| setFiles | array | n/a | Set value to the file field programmatically. See limitations below. |
| removeFiles | n/a | n/a | Remove all files on field |
setFiles()
Limitations:* Does not validate file size.
- Reads and validates file type via the `URL` passed.
- Files set programmatically are NOT auto uploaded.
Examples
Complete Example
<ins-input-file
label="Sample Attachment"
max-files="3"
max-file-size="2"
accepted-files="image/*,.pdf,.csv"
tooltip="This is a sample tooltip content. It also support html content.">
</ins-input-file>Error State
<ins-input-file
label="Error Field"
has-error error-message="This is a required field">
</ins-input-file>Disabled State
<ins-input-file
label="Disabled Field"
placeholder="This field is disabled"
disabled>
</ins-input-file>Direct Value Set
<ins-input-file
id="directFieldEl">
</ins-input-file>
<script>
var label = "Upload Image(s)";
var value = [{
name: "sample-image.jpg",
size: 12412,
type:"image/jpg",
url: "https://uploads.staging.oregon.platform-os.com/instances/2182/uploads/images/custom_image/image/194/thumb_aromatic-beverage-caffeine-2074122.jpg"
}]
var field = document.getElementById('directFieldEl');
field.addEventListener('didLoad', function(e){
field.label = label;
field.setFiles(value);
});
</script>Event Complete Example
<ins-input-file
label="Sample Attachment"
id="insFileEl"
max-files="10"
max-file-size="5"
tooltip="This is a sample tooltip content. It also support html content.">
</ins-input-file>
<p id="errors" style="font-size: 12px; color:#f27474; "></p>
<ins-button
solid
label="get files"
id="getFiles">
</ins-button>
<ins-button
color="green"
solid
label="Add File Programmatically"
id="addFiles">
</ins-button>
<ins-button
color="negative"
solid
label="Clear"
id="clearFiles">
</ins-button>
<script>
let insFileEl = document.getElementById("insFileEl");
let errorMessage = "";
// Event for when a file has been 'added'
insFileEl.addEventListener("fileAdded", (file) => {
console.log('Event: fileAdded', file.detail);
});
// Event for when a file has been 'removed'
insFileEl.addEventListener("fileRemoved", (file) => {
console.log('Event: fileRemoved', file.detail);
});
// Event when an 'error' encounted on attach / upload
// (ie. file size too big or file type not allowed)
insFileEl.addEventListener("fileError", (file) => {
// Display error message on an HTML element
document.getElementById('errors').innerHTML = "*"+file.detail.errorMessage;
// Remove error message after 5sec
setTimeout(() => {
document.getElementById('errors').innerHTML = "";
}, 5000);
});
// Button trigger to get files list
document.getElementById('getFiles').addEventListener("insClick", () => {
console.log("File(s) Attached", insFileEl.getFilesList());
alert("Check console log for data");
});
// Button trigger to add files programmatically from URL
document.getElementById('addFiles').addEventListener("insClick", () => {
insFileEl.setFiles([
// Example file object
{
name: "sample-image.jpg",
size: 32343,
type: "image/jpg",
url: "https://uploads.staging.oregon.platform-os.com/instances/2182/uploads/images/custom_image/image/194/thumb_aromatic-beverage-caffeine-2074122.jpg"
}
]);
});
// Button trigger to clear files list
document.getElementById('clearFiles').addEventListener("insClick", () => {
insFileEl.removeFiles();
console.log("Files Removed", insFileEl.getFilesList());
});
</script>Auto Upload Example
*Example does not actually upload. Use only for code reference
<ins-input-file
id="autoUploadEl"
max-files=3
auto-upload
accepted-files="image/*"
label="Example Auto Upload"
field-name="image_attachment"
field-type="image"
credentials-url="/api/reports/get-s3-credentials.json">
</ins-input-file>