Matterway
    Preparing search index...

    Function fileUpload

    • File upload component for handling file uploads with validation and limits.

      Parameters

      • props: UiUploadFileProps

        Configuration object

        • name

          Name of the component

        • fileUploadTitle

          Title text or React node for the upload section

        • text

          Helper text or React node to display

        • error

          Text or React node for the error message to display

        • loadingText

          Text to display during file upload. Default is 'loading'

        • maxFileLimit

          Maximum number of files allowed. Default is 1

        • minFileLimit

          Minimum number of files required. Default is 1

        • validate

          Async function to validate uploaded files. The file parameter will include a fully-loaded arrayBuffer, fetched automatically by the block. Works with Node.js libraries (e.g., exceljs)

        • allowedTypes

          Object containing an array of allowed file types (MIME types like 'application/pdf' or file extensions like '.pdf', '.jpg') and a message to display if the file type is not allowed

        • maxFileSize

          Object containing a size in bytes and a message to display if the file size is too large

      Returns Element

      • The component exposes two states: validFiles and droppedFiles. Every array element is the same object type.
        export interface DroppedMwFile {
         name: string;
         type: string;
         isValid?: boolean;
         message?: string;
         processedFile?: any;
         webUrl?: string;
         fileId: string;
         arrayBuffer?: ArrayBuffer;
        }
      • If file needs to be validated by file size, use maxFileSize prop.
      maxFileSize: {
        size: 5 * 1024 * 1024, // 5MB
        message: 'File size must be less than 5MB',
      }
      • If file needs to be validated by file type, use allowedTypes prop. You can specify MIME types (e.g. 'application/pdf') or file extensions (e.g., '.pdf', '.jpg').
      allowedTypes: {
        types: ['application/pdf', '.xlsx', '.docx'],
        message: 'File type must be an image, PDF, Excel, or Word document',
      }
      • The validate function's type definition is as follows:
      validate: (file: DroppedMwFile) => Promise<{
        isValid: boolean;
        message: string;
        processedFile?: any;
      }>;;
      • The validate function is optional. If not provided, all files will be considered valid.
      • The validate function is called when the user drops a file into the upload area or selects a file from the file system.

      Basic usage with required props

      fileUpload({
        name: 'upload-file',
        fileUploadTitle: 'Upload Files',
      });

      Usage with required and optional props

      fileUpload({
        name: 'upload-file',
        fileUploadTitle: 'Upload Files',
        text: 'Please select file to upload.',
        error: 'You can upload up to 3 files only.',
        maxFileLimit: 3,
        minFileLimit: 1,
      });

      Usage with file validate function (Node.js libraries supported)

      import {Workbook} from 'exceljs';

      fileUpload({
        name: 'upload-file',
        fileUploadTitle: 'Upload Excel Files',
        validate: async (file) => {
          // file.arrayBuffer is automatically fetched and available
          const wb = new Workbook();
          await wb.xlsx.load(file.arrayBuffer);

          // Perform validation
          if (wb.worksheets.length === 0) {
            return {
              isValid: false,
              message: 'Excel file must contain at least one worksheet'
            };
          }

          return {isValid: true, message: ''};
        }
      });

      Usage with file size and type validation (MIME types and extensions)

      fileUpload({
        name: 'upload-file',
        fileUploadTitle: 'Upload Files',
        maxFileSize: {
          size: 5 * 1024 * 1024, // 5MB
          message: 'File size must be less than 5MB',
        },
        allowedTypes: {
          types: ['application/pdf', '.xlsx', '.docx'],
          message: 'File type must be a PDF, Excel, or Word document',
        },

    Settings