upload

Renders a file upload input with built-in handling for images, video, audio, and documents within a submission form.

Usage

{% upload id: 'field_id', type: 'image', class: 'btn btn-primary' %}
  <span class="upload">Upload</span>
  <span class="uploading">Uploading...</span>
  <span class="uploaded">Uploaded</span>
{% endupload %}

The inner content is rendered inside a <label>. The .upload, .uploading, and .uploaded spans are not required, but are a standard pattern — bundled CSS uses these classes to reflect upload state automatically.

Options

Option	Type	Default	Description
type	string	image	File type — image, video, audio, or document
id	string	—	ID applied to the file input and its label
class	string	—	CSS classes on the wrapper <div>
accept	string	(see below)	Override the accepted MIME types
multiple	boolean	false	Allow multiple files — typically used with type: 'image' only
required	boolean	false	See note on validation below
thumb	string	—	Dimensions for a thumbnail to generate on upload, e.g. 400x400

File types

Default accepted MIME types and size limits by type:

Type	Accept	Max size
image	image/jpeg, image/png, image/gif	10MB
video	video/*	50MB
audio	audio/*	10MB
document	application/pdf, application/msword	4MB

Use the accept option to override the default for any type, e.g. accept: 'audio/mp3' or accept: 'application/pdf'.

Examples

Image upload:

{% upload id: 'image_profile', type: 'image', class: 'btn btn-primary d-block' %}
  <span class="upload">Upload</span>
  <span class="uploading">Uploading...</span>
  <span class="uploaded">Uploaded</span>
{% endupload %}

Multiple image upload:

{% upload id: 'gallery_images', type: 'image', class: 'btn btn-primary d-block', multiple %}
  <span class="upload">Upload</span>
  <span class="uploading">Uploading...</span>
  <span class="uploaded">Uploaded</span>
{% endupload %}

Video upload:

{% upload id: 'video_demo_reel', type: 'video', class: 'btn btn-primary d-block' %}
  <span class="upload">Upload</span>
  <span class="uploading">Uploading...</span>
  <span class="uploaded">Uploaded</span>
{% endupload %}

Audio upload with restricted MIME type:

{% upload id: 'audio_sample', type: 'audio', class: 'btn btn-primary d-block', accept: 'audio/mp3' %}
  <span class="upload">Upload</span>
  <span class="uploading">Uploading...</span>
  <span class="uploaded">Uploaded</span>
{% endupload %}

PDF document upload:

{% upload id: 'resume_pdf', type: 'document', class: 'btn btn-primary d-block', accept: 'application/pdf' %}
  <span class="upload">Upload</span>
  <span class="uploading">Uploading...</span>
  <span class="uploaded">Uploaded</span>
{% endupload %}

Events

Events are fired on the rendered wrapper <div class="syngency-uploader"> element.

Event	Description
uploadStarted	Fired when the file begins uploading to S3. The wrapper data-status is set to uploading.
uploadSuccess	Fired when the upload completes successfully. The wrapper data-status is set to uploaded. Passes an object with key (the S3 object key) and thumbUrl (the generated thumbnail URL, if thumb was set).
uploadError	Fired if the upload fails. The wrapper data-status is set to error.

Example:

$('.syngency-uploader').on('uploadSuccess', function (e, data) {
  console.log(data.key);      // S3 object key
  console.log(data.thumbUrl); // Thumbnail URL (if thumb option set)
});

Notes

• Validation: the required attribute is unreliable for upload fields since the underlying file input is never populated by the browser. The recommended approach is to validate using .required[data-status] — the wrapper element receives data-status="uploaded" once a file has been successfully uploaded, which can be checked before form submission. This is handled automatically when using Syngency themes.
• Previously uploaded values: if a value is present in GET or POST for the field id, the wrapper will render with data-status="uploaded" and a hidden input will be included to retain the value on submission.
• Allowed characters: option values are restricted to a-z A-Z 0-9 - _ / * space.