Twilight docs

A file uploader (drag and drop, browse, optional paste) built on FilePond that uploads to a URL you give it and keeps the result in a native form field.

A file uploader (drag and drop, browse, optional paste) built on FilePond that uploads to a URL you give it and keeps the result in a native form field. Use it for avatar upload (profile-image), attaching a file or image to a cart item (cart-item-id), product option file fields, or any form that needs an upload. Set allow-multiple with max-files-count for several files, and enable-gallery for a thumbnail strip with image and video limits. Any content inside the element is used as the idle drop-area label (unless label-idle is set); put a <span class="filepond--label-action"> around the "browse" text. Upload errors show as notifications. Place it inside a <form>: the uploaded file URL is written to a hidden input named like the file input, and a change event bubbles from it.

Use it

In HTML or JSX, use the tag <salla-file-upload> with the Attribute names below. In React, the wrapper takes the Property names (camelCase).

import { SallaFileUpload } from '@salla.sa/twilight-components-react/file-upload';

Client-only. On the server this wrapper renders a placeholder (a skeleton, or nothing), and the real component mounts in the browser. Do not rely on it for content that search engines must see.

Try it

web-components/salla-file-upload

Example

import { SallaFileUpload } from '@salla.sa/twilight-components-react/file-upload';

export function Example() {
  return (
    <form>
      <SallaFileUpload
        name="attachment"
        url="/api/upload"
        instantUpload
        accept="image/png, image/jpeg"
        maxFileSize="2MB"
        required />
    </form>
  );
}

Properties

Property	Attribute	Description	Type	Default
`accept`	`accept`	Accepted file types as a comma separated list of MIME types, for example `"image/png, image/jpeg"`. Defaults to PNG, JPEG and GIF images.	`string`	`"image/png, image/jpeg, image/jpg, image/gif"`
`allowBrowse`	`allow-browse`	Enable or disable file browser	`boolean`	`true`
`allowDrop`	`allow-drop`	Enable or disable drag n' drop	`boolean`	`true`
`allowImagePreview`	`allow-image-preview`	Enable or disable preview mode	`boolean`	`true`
`allowMultiple`	`allow-multiple`	Enable or disable adding multiple files	`boolean`
`allowPaste`	`allow-paste`	Enable or disable pasting of files. Pasting files is not supported on all browesrs.	`boolean`
`allowProcess`	`allow-process`	Enable or disable the process button	`boolean`
`allowRemove`	`allow-remove`	When set to false the remove button is hidden and disabled	`boolean`	`true`
`allowReorder`	`allow-reorder`	Allow users to reorder files with drag and drop interaction. Note that this only works in single column mode. It also only works on browsers that support pointer events.	`boolean`
`allowReplace`	`allow-replace`	Allow drop to replace a file, only works when allowMultiple is false	`boolean`	`true`
`allowRevert`	`allow-revert`	Enable or disable the revert processing button	`boolean`	`true`
`cartItemId`	`cart-item-id`	The id of a cart item. When set and `url` is empty, the upload goes to the cart image-upload endpoint and `instant-upload` is turned on. The id is also sent with the upload as `cart_item_id`. Used to attach a file to a cart item.	`string`
`checkValidity`	`check-validity`	Set to true to enable custom validity messages. FilePond will throw an error when a parent form is submitted and it contains invalid files.	`boolean`
`chunkForce`	`chunk-force`	Force chunks even for files smaller than the set chunkSize	`boolean`
`chunkRetryDelays`	`chunk-retry-delays`	Amount of times, and delayes, between retried uploading of a chunk	`number[]`	`[500, 1000, 3000]`
`chunkSize`	`chunk-size`	The size of a chunk in bytes	`number`	`5000000`
`chunkUploads`	`chunk-uploads`	Enable chunked uploads, when enabled will automatically cut up files in chunkSize chunks before upload.	`boolean`
`credits`	`credits`	Show credits at the bottom of the upload element. Structure is like [{label,url}] Deprecated: Not read by the component, so it has no effect. It will be removed in the next major version.	`boolean`
`disabled`	`disabled`	Disables the uploader so no files can be added.	`boolean`
`dropOnElement`	`drop-on-element`	Require drop on the FilePond element itself to catch the file.	`boolean`	`true`
`dropOnPage`	`drop-on-page`	FilePond will catch all files dropped on the webpage	`boolean`
`dropValidation`	`drop-validation`	When enabled, files are validated before they are dropped. A file is not added when it's invalid.	`boolean`
`enableGallery`	`enable-gallery`	Enable the custom gallery preview instead of FilePond thumbnails.	`boolean`	`false`
`fileId`	`file-id`	If current file has id, pass it here, to be passed back in the `removed` event Deprecated: Not read by the component, so it has no effect. It will be removed in the next major version.	`number`
`filePosterHeight`	`file-poster-height`	Fixed file poster height in pixels, overrides min and max preview height.	`number`	`null`
`files`	`files`	Existing uploaded files, as a JSON string `[{"url":"...","id":123}]`. They are shown on load, and `id` is passed back in the `removed` event. Takes precedence over `value` when both are set.	`string`
`forceRevert`	`force-revert`	Set to true to require the file to be successfully reverted before continuing.	`boolean`
`formData`	`form-data`	Extra fields for the upload request as a JSON string of name and value pairs, for example `'{"folder":"avatars"}'`. Entries with empty values are skipped. Not applied with `allow-multiple`.	`string`	`"{}"`
`height`	`height`	The original height of the uploader as a CSS value (for example `"150px"`). It is applied again to the uploader about one second after a file is removed.	`string`
`iconProcess`	`icon-process`	The icon used for process actions	`string`	`'<svg>...</svg>'`
`iconRemove`	`icon-remove`	The icon used for remove actions	`string`	`'<svg>...</svg>'`
`iconRetry`	`icon-retry`	The icon used for retry actions	`string`	`'<svg>...</svg>'`
`iconUndo`	`icon-undo`	The icon used for undo actions	`string`	`'<svg>...</svg>'`
`ignoredFiles`	`ignored-files`	Ignored file names when handling dropped directories. Dropping directories is not supported on all browsers.	`any[]`	`['.ds_store', 'thumbs.db', 'desktop.ini']`
`imagePreviewHeight`	`image-preview-height`	Fixed image preview height in pixels, overrides min and max preview height. Also sets the gallery thumbnail size when `enable-gallery` is on (default: 75).	`number`	`null`
`instantUpload`	`instant-upload`	Immediately upload new files to the server	`boolean`
`itemInsertInterval`	`item-insert-interval`	The interval to use before showing each item being added to the list	`number`	`75`
`itemInsertLocation`	`item-insert-location`	Set to 'after' to add files to end of list (when dropped at the top of the list or added using browse or paste), set to 'before' to add files at start of list. Set to a compare function to automatically sort items when added	`"after" \| "before" \| ((a: FilePondFile, b: FilePondFile) => number)`	`'after'`
`labelDecimalSeparator`	`label-decimal-separator`	The decimal separator used to render numbers. By default this is determined automatically.	`string`	`undefined`
`labelIdle`	`label-idle`	Default label shown to indicate this is a drop area. FilePond will automatically bind browse file events to the element with CSS class .filepond--label-action	`string`
`labelThousandsSeparator`	`label-thousands-separator`	The thousdands separator used to render numbers. By default this is determined automatically.	`string`	`undefined`
`maxFileSize`	`max-file-size`	The maximum size of a file, as a number followed by `MB` or `KB`, for instance `2MB` or `750KB`. If the store has an upload size setting, that setting is used instead for the limit.	`'${number}KB}' \| '${number}MB'`
`maxFilesCount`	`max-files-count`	The maximum number of files that can be added (a count). Ignored when `max-images-count` or `max-videos-count` is set.	`number`	`1`
`maxImagesCount`	`max-images-count`	Primary: maximum number of image files (split count mode). When set with or without maxVideosCount, maxFilesCount is ignored for count limits.	`number`
`maxParallelUploads`	`max-parallel-uploads`	The maximum number of files uploaded at the same time (a count).	`number`	`3`
`maxVideoDuration`	`max-video-duration`	Maximum video duration in seconds. Longer videos are rejected with an error notification.	`number`
`maxVideoFileSize`	`max-video-file-size`	Maximum size for video files only, e.g. 50MB or 750KB	`'${number}KB' \| '${number}MB'`
`maxVideosCount`	`max-videos-count`	Primary: maximum number of video files (split count mode). When set with or without maxImagesCount, maxFilesCount is ignored for count limits.	`number`
`method`	`method`	The submit request method.	`string`	`'POST'`
`name`	`name`	The name of the file input in the native form. Defaults to `file`, or `avatar` with `profile-image`.	`string`
`payloadName`	`payload-name`	The field name used for the file in the upload request when it must differ from `name`. Falls back to `name`. Not applied with `allow-multiple`, where files are sent as `files[]`.	`string`
`payloadParams`	`payload-params`	Extra fields to send with the upload request, as an object of name and value pairs (set it as a JS property). Not sent with `allow-multiple`.	`{ [x: string]: unknown; }`	`{}`
`profileImage`	`profile-image`	Makes this a profile image uploader with a preview and a circular shape. When `url` is empty it uploads to the profile update endpoint with `instant-upload` on, and `name` defaults to `avatar` unless you set the `name` attribute.	`boolean`	`false`
`required`	`required`	Makes the field required: the form cannot be submitted natively until a file has been uploaded.	`boolean`
`storeAsFile`	`store-as-file`	Tells FilePond to store files in hidden file input elements so they can be posted along with normal form post. This only works if the browser supports the DataTransfer constructor (https://caniuse.com/mdn-api_datatransfer_datatransfer), this is the case on Firefox, Chrome, Chromium powered browsers and Safari version 14.1 and higher.	`boolean`
`type`	`type`	A value sent to the server as the `type` field of the upload request. Only sent when `allow-multiple` is on.	`string`
`url`	`url`	The URL the file is uploaded to. The response is expected to be JSON with the file URL in `data` (`data.url`, `data.filePath`, or a string; an array when uploading several files). If empty, it is set automatically when `cart-item-id` or `profile-image` is used.	`string`
`value`	`value`	The current uploaded file. Set it to the file URL (a comma separated list of URLs for several files) to show an existing file. After an upload it becomes an object `{ id, url }` for the last uploaded file. With `profile-image` it starts as the current user's avatar.	`any`

Events

Listen with addEventListener, or the on prop of the React wrapper (for example onModalBack).

Event	Description	Detail
`added`	Fired when a file is added to the uploader. `event.detail` is `{ error, file }`: `error` is `null` on success, and `file` is the FilePond file item (with `filename`, `fileSize`, `fileType` and `file`).	`{ error: FilePondErrorDescription; file: FilePondFile; }`
`galleryUpdated`	Fired when the gallery preview list changes (after an upload or a removal). Only used with `enable-gallery`. `event.detail` is `{ count, imageCount, videoCount, uploading }`: the number of files (and of images and videos) and whether an upload is in progress.	`{ count: number; imageCount?: number; videoCount?: number; uploading?: boolean; }`
`invalidInput`	Fired when the form validates and the field is `required` but has no file. `event.detail` is the native `invalid` event.	`any`
`removed`	Fired when a file is removed. `event.detail` is the id of the removed file when known (the `id` from `files` or the upload), otherwise its URL, server id or FilePond file id.	`number \| string`
`uploaded`	Fired after a file has been uploaded and the server returned its link. `event.detail` is the current `value`: an object `{ id, url }` for the uploaded file.	`string`