msc-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.

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": false,
          "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.

<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>

Properties

| 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. 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 's fetching status. | | uploadInfo | Array | Getter for 's current uploaded information. Developers could check error key exist to know data is clean to take or not. | | count | Number | Getter for current '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 occured errors (validation & fetch). Developers can gather information through event.detail. ( will put server response to event.detail.cause) | | msc-image-uploader-remove | Fired when removed unit successed. | | msc-image-uploader-upload-done | Fired when finished fetching. |

Reference

• <msc-image-uploader />
• WEBCOMPONENTS.ORG
• YouTube