Image Upload

A single-image upload control with a live preview. Wrap a native <input type="file"> in .wf-imgup[data-wf-image-upload] and the JS replaces it with a clickable preview area. The native input stays hidden, so standard form submissions work with zero changes.

Basic

Drag-and-drop is supported in all shapes. Validation errors (type, file size, and pixel dimensions) are surfaced via WojoToast . An initial server image can be shown via data-wf-preview-src .

import './wf-image-upload.js'

<!-- Auto-init -->
<div class="wf-imgup" data-wf-image-upload>
  <input type="file" name="avatar" accept="image/*">
</div>

<!-- Manual init -->
<div class="wf-imgup" id="my-uploader">
  <input type="file" name="avatar" accept="image/*">
</div>
<script type="module">
  import { WojoImageUpload } from './wf-image-upload.js'
  const uploader = new WojoImageUpload(document.getElementById('my-uploader')).init()
</script>

Shapes

Set data-wf-shape to one of four values. The default is rounded . All shapes are square aspect ratio except rectangle , which uses a wide 16:9 proportion.

<!-- Rounded corners (default) -->
<div class="wf-imgup" data-wf-image-upload data-wf-shape="rounded">
  <input type="file" name="photo" accept="image/*">
</div>

<!-- Square with minimal radius -->
<div class="wf-imgup" data-wf-image-upload data-wf-shape="square">
  <input type="file" name="logo" accept="image/*">
</div>

<!-- Circle avatar -->
<div class="wf-imgup" data-wf-image-upload data-wf-shape="circle">
  <input type="file" name="avatar" accept="image/*">
</div>

<!-- Rectangle banner (wide aspect ratio) -->
<div class="wf-imgup" data-wf-image-upload data-wf-shape="rectangle">
  <input type="file" name="banner" accept="image/jpeg,image/png,image/webp">
</div>

Sizes

Set data-wf-size to sm or lg . The default medium size is 10rem square ( 18×10rem rectangle). Fine-tune with CSS custom properties .

<div class="wf-imgup" data-wf-image-upload data-wf-shape="circle" data-wf-size="sm">
  <input type="file" name="avatar" accept="image/*">
</div>

<div class="wf-imgup" data-wf-image-upload data-wf-shape="circle">
  <input type="file" name="avatar" accept="image/*">
</div>

<div class="wf-imgup" data-wf-image-upload data-wf-shape="circle" data-wf-size="lg">
  <input type="file" name="avatar" accept="image/*">
</div>

Validation

Client-side validation runs on every file selection and drag-drop. Failures are shown as toast notifications via WojoToast and the input is reset so the same file can be corrected and re-submitted. Three types of checks are available and can be combined freely.

File size

<!-- Reject files larger than 2 MB (2 097 152 bytes) -->
<div class="wf-imgup" data-wf-image-upload
     data-wf-max-size="2097152">
  <input type="file" name="photo" accept="image/*">
</div>

Pixel dimensions

Min and max width/height are checked after the file passes the size test. Mix and match as needed — any omitted limit defaults to unlimited (0).

<!-- Banner: at least 400px wide, max 1920×640 -->
<div class="wf-imgup" data-wf-image-upload
     data-wf-shape="rectangle"
     data-wf-min-width="400"
     data-wf-max-width="1920"
     data-wf-max-height="640">
  <input type="file" name="banner" accept="image/jpeg,image/png,image/webp">
</div>

Pre-populate

Use data-wf-preview-src to show the currently saved image on page load — for example when rendering an edit form server-side. No file is staged; the attribute is display-only. The user can then pick a new file to replace it or click the remove button to clear it.

<div class="wf-imgup" data-wf-image-upload
     data-wf-shape="circle"
     data-wf-preview-src="/uploads/current-avatar.jpg">
  <input type="file" name="avatar" accept="image/*">
</div>

Data Attributes

Place all attributes on the .wf-imgup wrapper element.

Native input attributes

Placed on the <input type="file"> inside the wrapper. The multiple attribute is always removed — this component is single-file only.

CSS Custom Properties

These properties are declared on :root and can be overridden on .wf-imgup or any ancestor.

.wf-imgup {
  --wf-imgup-size:       12rem;   /* square size  */
  --wf-imgup-rect-w:     22rem;   /* rectangle width  */
  --wf-imgup-rect-h:     12rem;   /* rectangle height */
  --wf-imgup-border:     #d0d0d0;
  --wf-imgup-bg:         #f5f5f5;
  --wf-imgup-overlay-bg: rgba(0,0,0,.5);
  --wf-imgup-speed:      .15s;
}

Programmatic API

After initialization the instance is stored on the wrapper element as el._wfImageUpload .

const el = document.querySelector('[data-wf-image-upload]')
const uploader = el._wfImageUpload

uploader.setPreviewUrl('/uploads/saved.jpg') // show server image
uploader.getFile()                           // returns File or null
uploader.clear()                             // remove preview & reset
uploader.setDisabled(true)                   // disable
uploader.destroy()                           // remove listeners & revoke URL

Events

Both events are dispatched on the .wf-imgup wrapper and bubble up the DOM.

const el = document.querySelector('[data-wf-image-upload]')

el.addEventListener('wf:image-change', e => {
  console.log('New image file:', e.detail.file)
  // e.detail.file is the validated File object
})

el.addEventListener('wf:image-remove', () => {
  console.log('Image was cleared')
})

i18n

Register a locale globally with WojoI18n before DOMContentLoaded . Any key you omit falls back to the built-in English default. Use {max} in error size messages and {min} / {max} in dimension messages.

import { WojoI18n } from './wf-base.js'

WojoI18n.setLocale('fr')
WojoI18n.register('fr', {
  imageUpload: {
    chooseLabel:      'Choisir une image',
    changeLabel:      'Changer l\'image',
    removeLabel:      'Supprimer',
    placeholderLabel: 'Cliquez ou déposez une image',
    errorType:        'Type de fichier invalide.',
    errorSize:        'Fichier trop volumineux. Max : {max}.',
    errorMinWidth:    'Image trop étroite. Largeur min : {min}px.',
    errorMinHeight:   'Image trop petite. Hauteur min : {min}px.',
    errorMaxWidth:    'Image trop large. Largeur max : {max}px.',
    errorMaxHeight:   'Image trop haute. Hauteur max : {max}px.',
  }
})

<!-- Per-instance overrides (highest priority) -->
<div class="wf-imgup" data-wf-image-upload
     data-wf-i18n-choose-label="Wählen Sie ein Bild"
     data-wf-i18n-placeholder-label="Klicken oder ablegen"
     data-wf-i18n-error-size="Datei zu groß. Max: {max}.">
  <input type="file" name="avatar" accept="image/*">
</div>

i18n keys

Class Reference

All modifier classes available on .wf-imgup