@joystick.js/ui

Upload

Upload files from Joystick components to a server-defined uploader.

If you've defined an uploader config on the server, you can upload files via the upload() method imported from @joystick.js/ui on your component.

Example Usage

ui/pages/index/index.js

import joystick, { upload } from '@joystick.js/ui';

const Index = joystick.component({
  events: {
    'submit form': (event = {}, instance = {}) => {
      event.preventDefault();
      upload('example_uploader', {
        files: event.target.file.files,
        input: {
          additional_data: 'some arbitrary data to send with the upload',
        },
      }).then((response) => {
        // Response contains URLs for uploaded files.
      });
    },
  },
  render: () => {
    return `
      <form>
        <label>File</label>
        <input type="file" name="file" />
        <button type="submit">Upload File</button>
      </form>
    `;
  },
});

export default Index;

To upload a file, import the named export upload from @joystick.js/ui. In the submit event handler for the <form></form>, call upload(), passing the name of the uploader on the server (example_uploader) and an options object. This object includes the files to upload and an optional input object with metadata to send alongside the upload.

Monitoring Progress

Upload progress is automatically tracked by Joystick across all configured providers for your uploader. As progress occurs, the on_progress() method in the upload() options is called, passing the current progress percentage and the name of the provider handling the upload.

ui/pages/index/index.js

import joystick, { upload } from '@joystick.js/ui';

const Index = joystick.component({
  state: {
    upload_progress: 0,
  },
  events: {
    'submit form': (event = {}, instance = {}) => {
      event.preventDefault();
      upload('example_uploader', {
        files: event.target.files.files,
        input: {
          additional_data: 'some arbitrary data to send with the upload',
        },
        on_progress: (percentage = 0, provider = '') => {
          instance.set_state({ upload_progress: percentage }); 
        },
      }).then((response) => {
        // Response contains URLs for uploaded files.
      });
    },
  },
  render: ({ state, when }) => {
    return `
      ${when(state.upload_progress, `
        <p>Uploading: ${state.upload_progress}%...</p>
      `)}
      <form>
        <label>File</label>
        <input type="file" name="file" />
        <button type="submit">Upload File</button>
      </form>
    `;
  },
});

export default Index;

API

Definition

upload(uploader_name: string, uploader_options: object) => Promise;

Parameters

uploader_name string required
The name of the uploader to target on the server.
uploader_options object required
Options for the upload being performed.
files array[File] required
An array of File objects from the browser representing the files to upload.
input object
An object of arbitrary key/value pairs to send to the server alongside the files.
on_progress function
A function that receives the current upload progress percentage (integer) and the provider name (string).