Guides
Login

Web upload events and attributes

Suggest Edits

Our web uploads SDK offers a robust mechanism for tracking the upload lifecycle through various events and attributes. These events provide real-time feedback and insights into the upload process, enabling developers to build custom user interfaces, monitor progress, and handle errors effectively. The attributes allow further customization, ensuring the component behaves exactly as required for different use cases.


Stay informed with events

The component keeps you informed about the upload process through various events it fires throughout the lifecycle. These events mirror the events triggered by fp-resumable-uploads, the library powering the chunked upload functionality.


Understanding the events

Here's a breakdown of the available events and what they signify:

  • fileReady: This event fires as soon as you select a file for upload, indicating it's ready to be processed.
  • uploadStart: This event signifies the beginning of the upload process for the selected file.
  • chunkAttempt: This event triggers right before each individual chunk of the file gets attempted for upload.
  • chunkSuccess: This event fires when a specific chunk is uploaded successfully. It provides details like the chunk number, attempt count, and the response received from the server (if any).
  • uploadError: This event triggers if an error occurs during the chunked upload process.
  • progress: This event continuously fires with updated upload progress. It provides the percentage of the file that has been uploaded so far.
  • success: This event signifies the successful completion of the entire file upload.

EXTRA TIP

For larger files uploads, you can display estimated completion times based on the process event to give users more accurate expectations.


Benefits of using events

By listening to these events, you can:

  • Provide real-time feedback to users about the upload status.
  • Implement custom logic based on different upload stages (e.g., display a loading indicator, handle errors gracefully).
  • Track upload progress and update a progress bar visually.
  • Build your own upload UI: Leverage the events to create a custom user interface tailored to your application's needs. By simply passing the endpoint attribute to the component and disabling it, you can gain full control over the upload process visualization. You can then trigger actions and update the UI based on the fired events. This approach grants you maximum flexibility in designing the upload experience.

TIPS

  • If you're building a custom UI, consider using a loading animation during the uploadStart event and replacing it with a success event is fired.
  • Create an additional fallback features by triggering an automatic retry after the uploadError event, saving user from manually attempting to restart uploads.

How to use events

The specific method for using web upload events will depend on the framework or library you're using with fp-upload. However, the general approach involves attaching event listeners to the fp-upload component. These listeners will be called whenever the corresponding event fires.


<fp-upload endpoint="signed-url" id="webUploads"></fp-upload> 

 

<script> 

  const uploader = document.getElementById('webUploads'); 

  uploader.addEventListener('fileReady', (event) => { 

  console.log('A file has been selected for upload:', event.detail); 

}); 

  uploader.addEventListener('uploadStart', (event) => { 

  console.log('Upload process has begun for:', event.detail.file.name); 

}); 

  uploader.addEventListener('success', (event) => { 
  console.log('File upload completed successfully:', event.detail); 
}); 


uploader.addEventListener('progress', (event) => { 

  const progress = event.detail; 
    console.log(`Upload progress: ${progress}%`); 
  }); 

  uploader.addEventListener('chunkAttempt', (event) => { 
    console.log('Chunk upload attempt:', event.detail); 
  }); 

  uploader.addEventListener('chunkSuccess', (event) => { 
    console.log('Chunk upload successful:', event.detail); 
  }); 

  

  uploader.addEventListener('uploadError', (event) => { 
    console.log('An error occurred during upload:', event.detail); 
  }); 

</script>

Web upload attributes

The component provides various attributes for customizing its behaviour and appearance. Here's a breakdown of these attributes:

Essential attributes:

  • endpoint (string | Promise): This is a required attribute. It specifies the URL where your uploaded file will be sent. You can either provide the URL directly as a string or use an asynchronous function that returns a promise resolving to the upload URL.
  • id (string): This attribute assigns a unique identifier to the component. It can be useful for referencing the uploader in your JavaScript code. This is especially required when you need to access multiple upload instances on the same page.

Visual indicators (Read-only):

  • file-progress-update(boolean): Controls the visual representation of the progress bar while the upload is ongoing. This feature can be targeted using CSS if you wish to customize its appearance while the upload is in progress.
  • file-progress-error (boolean): Controls the visual status of the progress bar when an error occurs during the upload process. This feature can be targeted using CSS if you want to customize its appearance when an error occurs

Customization options:

  • disable-drop (boolean): Disables the drag and drop functionality when this attribute is included.
  • disable-monitor (boolean): Disables the display of the built-in progress bar element within the . Defaults to false. This can be useful if you want to create a custom progress bar using JavaScript.
  • disable-retry (boolean): Disables the display of the retry button when the file upload fails.
  • disable-status (boolean): Hides the built-in status messages displayed by . Defaults to false. You might use this if you want to handle displaying upload status information using JavaScript.
  • max-file-size (number): This attribute allows you to enforce a limit on the maximum file size accepted by the uploader on the client-side. This provides a user-friendly way to prevent users from selecting files exceeding the server's capacity. Value to be specified in KB.
  • chunk-size (number): Users can specify their desired chunk size through this attribute in KB. The minimum chunk size should be 5120 KB.
  • overlay-text (string) : This attribute is used in the and components. This attribute displays custom text when a video file is hovered over these components, providing users with clear feedback

Video uploads in your forms

This example showcases how the component facilitates video uploads within your web forms. Imagine building a platform for a video contest. Using , you can create a user-friendly interface to collect entries, including fields for:

Video title: Allow users to name their submissions.

Video upload: Integrate a dedicated field for video file selection.

Optional features:

  • Thumbnail image upload: Enable users to upload a preview image for their video.

Technical implementation

Server-side upload URL generation: When a form page is requested, the server generates a unique direct upload URL using the component. This URL is then sent to the client-side along with an upload ID.


Client-side integration

  • The component on the client-side utilizes the received upload URL and ID to handle the video upload process.
  • For enhanced security, the submit button remains disabled until the upload is complete, guaranteeing a smooth experience.

This example demonstrates the versatility of the component for handling video uploads within your web forms in React Project. It empowers developers to create a user-friendly and secure video submission experience.

function WebUploads() {

  const [posterFile, setPosterFile] = useState(null);
  const [audioFile, setAudioFile] = useState(null);
  const [fileUploaded, setFileUploaded] = useState(false)

  const handlePosterChange = (event) => {
    setPosterFile(event.target.files[0]);
  };

  const handleAudioUpload = (event) => {
    setAudioFile(event.target.files[0]);
  };

  const triggerPosterInput = () => {
    document.getElementById('poster-upload').click();
  };

  const triggerAudioInput = () => {
    document.getElementById('audio-upload').click();
  };

  useEffect(() => {
    const uploader = document.getElementById("webUploads")
    uploader.addEventListener("success", () => {
      setFileUploaded(true)
    })
  }, [])

  return (
    <div className="container">
      <div className="subContainer">
        <h2 className="header">Submit your video</h2>
        <form>
          <div className="inputContainer">
            <label className="inputLabel" htmlFor="video-title">Video Title:</label>
            <input autoComplete="off" className="inputTitle" name="videoTitle" id="video-title" type="text"></input>
          </div>
          <div className="inputContainer">
            <label className="inputLabel" htmlFor="poster-upload">Upload Poster:</label>
            <input
              name="posterUpload"
              id="poster-upload"
              type="file"
              accept="image/*"
              onChange={handlePosterChange}
              style={{ display: 'none' }}
            />
            <button type="button" onClick={triggerPosterInput} className="buttonUpload">Upload Poster</button>
            {posterFile && <div className="posterFileName">{posterFile.name}</div>}
          </div>
          <div className="inputContainer">
            <label className="inputLabel" htmlFor="poster-upload">Upload Audio:</label>
            <input
              name="audioUpload"
              id="audio-upload
              type="file"
              accept="audio/*"
              onChange={handleAudioUpload}
              style={{ display: 'none' }}
            />
            <button type="button" onClick={triggerAudioInput} className="buttonUpload">Upload Audio</button>
            {audioFile && <div className="posterFileName">{audioFile.name}</div>}
          </div>
          <fp-upload overlay-text="Drop your video" class="uploaderContainer" endpoint="signed-url" id="webUploads">
            <button className="buttonUpload" slot="upload-file-button">Upload Video</button>
          </fp-upload>
          <button className={`submitButton buttonUpload ${fileUploaded ? "" : "disabled"}`}>Submit</button>
        </form>
      </div>
    </div>
  )
}




* {
  box-sizing: border-box;
  padding: 0px;
  margin: 0px;
}

.container {
  background-color: #ffffff;
  height: 100vh;
  padding: 20px;
}

.header {
  color: #444348;
  font-weight: 500;
  text-align: center;
}

.subContainer {
  border: 1px solid #bebaba;
  border-radius: 10px;
  height: 100%;
  padding: 20px;
}

.inputContainer {
  margin-top: 40px;
  display: flex;
  flex-direction: column;
}

.inputLabel {
  color: #3e3d3d;
  font-size: 18px;
  font-weight: 500;
}
.inputTitle {
  height: 40px;
  width: 100%;
  margin-top: 5px;
  border: 0px;
  border-radius: 5px;
  font-size: 16px;
  padding: 10px;
  outline: none;
  border: 0.75px solid #bebaba;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.inputTitle:focus {
  border: 1px solid #2892b9;
  /* Changes border color on focus */
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
  /* Optional: enhance the shadow on focus */
}

.uploaderContainer {
  border: 1px double #a2a0a8;
  color: #3e3d40;
  margin-top: 20px;
  height: 250px;
  background-color: #ffffff;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  --uploader-progress-fill-color: #2892b9;
  --uploader-overlay-background-color: #a7e6fb;
}

.buttonUpload {
  background-color: #2892b9;
  border: 0px;
  width: 150px;
  height: 48px;
  margin-top: 5px;
  cursor: pointer;
  border-radius: 5px;
  color: #f9f8fb;
  font-size: 16px;
}

.buttonUpload:active {
  background-color: #eee;
  border-color: #010023;
}

.uploadStatus {
  color: #2892b9;
}



.submitButton {
  margin-top: 40px;
  background-color: #496e7c;
  opacity: 1;
  cursor: pointer;
}

.submitButton.disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

Updated 21 days ago