Image Uploader

<msc-image-uploader /> is a web component based image uploader. Users could pick & upload images by 「file picker」、「drag & drop」and even direct「paste」image content. Besides that, users could also change images sorting through 「drag & drop」or 「keyboard arrow keys」.

With rich config setting, developers can set up placeholder and limitation for different scenarios. Let's check what can <msc-image-uploader /> do ?

Basic Usage

<msc-image-uploader /> is a web component. All we need to do is put the required script into your HTML document. Then follow <msc-image-uploader />'s html structure and everything will be all set.

Required Script

<script type="module" src="https://your-domain/wc-msc-image-uploader.js"> </script>

Structure

Put <msc-image-uploader /> into HTML document. It will have different functions and looks with attribute mutation.

<msc-image-uploader> <script type="application/json"> { "fieldname": "image", "multiple": true, "limitation": { "size": 52428800, "accept": ".jpg,.jpeg,.png,.gif,.webp,.avif", "minwidth": 100, "minheight": 100, "maxcount": 10 }, "placeholder": [ { "src": "https://your-domain/img/img-0.jpg", "crumb": "dsaRxsa" }, { "src": "https://your-domain/img/img-1.jpg", "crumb": "ptScwKdQ" } ], "webservice": { "url": "https://your-domain/uploadApi", "params": { "id": "mei", "sex": "M" }, "header": { "content-type": "application/json" }, "withCredentials": true, "timeout": 30000 } } </script> </msc-image-uploader>

Otherwise, developers could also choose remoteconfig to fetch config for <msc-image-uploader />.

<msc-image-uploader remoteconfig="https://your-domain/api-path" > </msc-image-uploader>

JavaScript Instantiation

<msc-image-uploader /> could also use JavaScript to create DOM element. Here comes some examples.

<script type="module"> import { MscImageUploader } from 'https://your-domain/wc-msc-image-uploader.js'; // use DOM api const nodeA = document.createElement('msc-image-uploader'); document.body.appendChild(nodeA); nodeA.webservice = { url: 'https://your-domain/uploadApi' }; nodeA.fieldname = 'image'; // new instance with Class const nodeB = new MscImageUploader(); document.body.appendChild(nodeB); nodeB.limitation = { accept: '.jpg,.jpeg,.png', minwidth: 200, minheight: 200 }; // new instance with Class & default config const config = { fieldname: 'image', multiple: false, limitation: { size: 52428800, accept: '.jpg,.jpeg,.png,.gif,.webp,.avif', minwidth: 100, minheight: 100, maxcount: 10 }, placeholder: [], webservice: { url: '/', params: {}, header: {}, withCredentials: false, timeout: 30000 } }; const nodeC = new MscImageUploader(config); document.body.appendChild(nodeC); </script>

Storage

<msc-image-uploader /> will generate an input[type=hidden] as storage and put success uploaded data as its value. <input /> default name is msc-image-upload, developers can switch any name they liked.

<msc-image-uploader> <input type="hidden" name="msc-image-uploader" value="..." /> </msc-image-uploader>

Style Customization

Developers could apply styles to decorate <msc-image-uploader />'s looking.

<style> msc-image-uploader { --msc-image-uploader-gap: 12px; --msc-image-uploader-column-count: 4; --msc-image-uploader-dragging-opacity: .5; --msc-image-uploader-unit-border-radius: 8px; --msc-image-uploader-focus-within-bgc: rgba(255 255 255/.01); --msc-image-uploader-main-drop-overlay-color: rgba(0 0 0/.7); --msc-image-uploader-main-drop-hint-text-color: rgba(255 255 255); --msc-image-uploader-main-drop-hint-text-size: 40px; --msc-image-uploader-main-drop-hint-text: 'DROP IMAGES HERE.'; --msc-image-uploader-label-bgc: rgba(232 234 237/.04); --msc-image-uploader-label-color: #606367; --msc-image-uploader-label-hint-text: 'pick images'; --msc-image-uploader-loading-color: rgba(255 255 255); --msc-image-uploader-loading-bgc: rgba(0 0 0/.05); } </style>

Otherwise, apply pseudo class ::part(decoration) to direct style each unit. Besides that, developers could also apply pseudo class ::part(decoration-{n}) for specific unit.

<style> msc-image-uploader::part(decorations)::before { position: absolute; inset-inline-start: 0; inset-block-start: 0; content: 'image'; font-size: 12px; color: #fff; background-color: rgba(0 0 0/.8); padding: 2px 6px; border-end-end-radius: 4px; display: none; } msc-image-uploader::part(decorations-1)::before { content: '1st'; color: #f00; } </style>

Apply class - msc-image-uploader--blank-trigger will turn trigger into blank mode. That means trigger won't occupy any space and developers could use it for some special cases. Such as the following single image uploade.

<style> msc-image-uploader { --msc-image-uploader-column-count: 1; --msc-image-uploader-gap: 0px; --msc-image-uploader-main-drop-hint-text: 'DROP HERE'; --msc-image-uploader-main-drop-hint-text-size: 16px; } </style> <msc-image-uploader class="msc-image-uploader--blank-trigger"> <script type="application/json"> { "limitation": { "size": 52428800, "accept": ".jpg,.jpeg,.png,.gif,.webp,.avif", "width": 400, "height": 400, "maxcount": 1 }, "webservice": { "url": "https://your-domain/uploadApi", "params": {}, "header": {}, "withCredentials": false, "timeout": 30000 } } </script> </msc-image-uploader>

Attributes

<msc-image-uploader /> supports some attributes to let it become more convenience & useful.

fieldname

Set fieldname for <msc-image-uploader />. Each upload image fetch will apply this ad file's field name. Default is image (not set).

<msc-image-uploader fieldname="image" > ... </msc-image-uploader>

limitation

Set limitation for <msc-image-uploader />. It should be JSON string. <msc-image-uploader /> will go through these rules when user picked files. Default is list in following sample (not set).

- size：max file size (byte). Default is 52428800.
- accept：accepted able types. Default is .jpg,.jpeg,.png,.gif,.webp,.avif.
- minwidth：image min-width (px). Default is 100.
- minheight：image min-height (px). Default is 100.
- maxcount：Max file count. Default is 10.

<msc-image-uploader limitation='{"size":52428800,"accept":".jpg,.jpeg,.png,.gif,.webp,.avif","minwidth":100,"minheight":100,"maxcount":10}' > ... </msc-image-uploader>

webservice

Set web service information for <msc-image-uploader />. It should be JSON string. Developers could set url、params、header、withCredentials and timeout here.

- url：api address for upload image. Default is /.
- params：Set parameters. Each of them will be attached with fetch. Default is {}.
- header：Set fetch header. Default is {}.
- withCredentials：Set withCredentials for fetch. Default is false.
- timeout：Set timeout for fetch. Default is 30000 (ms).

<msc-image-uploader webservice='{"url":"/","params":{},"header":{},"withCredentials":false,"timeout":30000}' > ... </msc-image-uploader>

placeholder

Set placeholder for <msc-image-uploader />. It should be JSON string. Each element should include src for thumbnail display. Default is [] (not set).

<msc-image-uploader placeholder='[{"src":"https://your-domain/img/img-0.jpg","other":"xxx"},{"src":"https://your-domain/img/img-1.jpg","other":"xxx"}]' > ... </msc-image-uploader>

multiple

Enable <msc-image-uploader /> multiple files picked mode. Default is false (not set).

<msc-image-uploader multiple > ... </msc-image-uploader>

Property

Property Name Type Description
fieldname String Getter / Setter for fieldname. Each upload image fetch will apply this ad file's field name. Default is image (not set).
limitation Object Getter / Setter for limitation. <msc-image-uploader /> will go through these rules when user picked files.
webservice Object Getter / Setter for web service information. Developers could set url、params、header、withCredentials and timeout.
placeholder Array Getter / Setter for placeholder. Each element should include src for thumbnail display. Default is [] (not set).
multiple Boolean Getter / Setter for multiple. Enable multiple files picked mode. Default is false (not set).
processing Boolean Getter for <msc-image-uploader />'s fetching status.
uploadInfo Array Getter for <msc-image-uploader />'s current uploaded information. Developers could check error key exist to know data is clean to take or not.
count Number Getter for current <msc-image-uploader />'s uploaded units count.

Method

Method Signature Description
showPicker Summon native file picker.
removeAll Remove all uploaded units.

Event

Event Signature Description
msc-image-uploader-pick Fired when users picked files.
msc-image-uploader-error Fired when <msc-image-uploader /> occured errors (validation & fetch). Developers can gather information through event.detail.

(<msc-image-uploader /> will put server response to event.detail.cause)
msc-image-uploader-remove Fired when <msc-image-uploader /> removed unit(s) successed.
msc-image-uploader-upload-done Fired when <msc-image-uploader /> finished fetching.

Reference