File Upload

Upload files with your form submissions using the file block type.

Quick Start

Add a file input to your form using the fi-file-{name} naming pattern:

<form id="application-form" enctype="multipart/form-data">
  <input type="text" name="fi-sender-fullName" placeholder="Full name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  <input type="file" name="fi-file-resume" accept=".pdf,.doc,.docx" />
  <button type="submit">Submit Application</button>
</form>

Field Naming

File fields follow the standard Forminit naming convention:

Pattern	Example	Description
`fi-file-{name}`	`fi-file-resume`	Single file upload named “resume”
`fi-file-{name}[]`	`fi-file-attachments[]`	Multiple files (with `multiple` attribute)

The {name} identifier must be unique across all blocks in your form and cannot contain spaces. Always append [] when using the multiple attribute.

Single File Upload

For uploading one file:

<input type="file" name="fi-file-resume" />

With file type restrictions:

<input type="file" name="fi-file-resume" accept=".pdf,.doc,.docx" />

Common accept patterns:

Accept Value	File Types
`.pdf`	PDF documents
`.doc,.docx`	Word documents
`.jpg,.jpeg,.png,.gif`	Images
`.csv,.xlsx,.xls`	Spreadsheets
`image/*`	All image types
`application/pdf`	PDF by MIME type

Multiple File Uploads

Add the multiple attribute and append [] to the field name to allow selecting multiple files:

<input type="file" name="fi-file-attachments[]" multiple />

Multiple file inputs with different names:

<input type="file" name="fi-file-resume" accept=".pdf" />
<input type="file" name="fi-file-cover_letter" accept=".pdf,.doc,.docx" />
<input type="file" name="fi-file-portfolio[]" accept="image/*" multiple />

Important: When using the multiple attribute, always add [] to the end of the field name (e.g., fi-file-photos[]). This is required for proper server-side handling of multiple files.

Framework Examples

HTML / Static Website

<form id="job-application">
  <input type="text" name="fi-sender-firstName" placeholder="First name" required />
  <input type="text" name="fi-sender-lastName" placeholder="Last name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  <input type="tel" name="fi-sender-phone" placeholder="Phone" />
  
  <textarea name="fi-text-cover_letter" placeholder="Cover letter"></textarea>
  
  <label>Resume (PDF)</label>
  <input type="file" name="fi-file-resume" accept=".pdf" required />
  
  <label>Work Samples (optional)</label>
  <input type="file" name="fi-file-samples[]" multiple />
  
  <button type="submit">Submit Application</button>
</form>

<p id="form-result"></p>

<script src="https://forminit.com/sdk/v1/forminit.js"></script>
<script>
  const forminit = new Forminit();
  const FORM_ID = 'YOUR_FORM_ID';
  
  document.getElementById('job-application').addEventListener('submit', async (e) => {
    e.preventDefault();
    
    const formData = new FormData(e.target);
    const { data, error } = await forminit.submit(FORM_ID, formData);
    
    if (error) {
      document.getElementById('form-result').textContent = error.message;
      return;
    }
    
    document.getElementById('form-result').textContent = 'Application submitted!';
    e.target.reset();
  });
</script>

Next.js

'use client';

import { useState, useRef } from 'react';
import { Forminit } from 'forminit';

export function ApplicationForm() {
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
  const [error, setError] = useState<string | null>(null);
  const formRef = useRef<HTMLFormElement>(null);
  const forminit = new Forminit({ proxyUrl: '/api/forminit' });

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    setStatus('loading');
    setError(null);

    const formData = new FormData(e.currentTarget);
    const { data, error } = await forminit.submit('YOUR_FORM_ID', formData);

    if (error) {
      setStatus('error');
      setError(error.message);
      return;
    }

    setStatus('success');
    formRef.current?.reset();
  }

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      <input type="text" name="fi-sender-firstName" placeholder="First name" required />
      <input type="text" name="fi-sender-lastName" placeholder="Last name" required />
      <input type="email" name="fi-sender-email" placeholder="Email" required />
      
      <label>Resume</label>
      <input type="file" name="fi-file-resume" accept=".pdf,.doc,.docx" required />
      
      <label>Portfolio (optional)</label>
      <input type="file" name="fi-file-portfolio[]" multiple />
      
      {status === 'error' && <p className="error">{error}</p>}
      {status === 'success' && <p className="success">Application submitted!</p>}
      
      <button type="submit" disabled={status === 'loading'}>
        {status === 'loading' ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  );
}

Nuxt.js

<script setup lang="ts">
import { ref } from 'vue';
import { Forminit } from 'forminit';

const FORM_ID = 'YOUR_FORM_ID';

const status = ref<'idle' | 'loading' | 'success' | 'error'>('idle');
const errorMessage = ref<string | null>(null);
const formRef = ref<HTMLFormElement | null>(null);

const forminit = new Forminit({ proxyUrl: '/api/forminit' });

async function handleSubmit() {
  if (!formRef.value) return;
  
  status.value = 'loading';
  errorMessage.value = null;

  const formData = new FormData(formRef.value);
  const { data, error } = await forminit.submit(FORM_ID, formData);

  if (error) {
    status.value = 'error';
    errorMessage.value = error.message;
    return;
  }

  status.value = 'success';
  formRef.value.reset();
}
</script>

<template>
  <form ref="formRef" @submit.prevent="handleSubmit">
    <input type="text" name="fi-sender-firstName" placeholder="First name" required />
    <input type="text" name="fi-sender-lastName" placeholder="Last name" required />
    <input type="email" name="fi-sender-email" placeholder="Email" required />
    
    <label>Resume</label>
    <input type="file" name="fi-file-resume" accept=".pdf,.doc,.docx" required />
    
    <label>Additional Documents</label>
    <input type="file" name="fi-file-documents[]" multiple />
    
    <p v-if="status === 'error'" class="error">{{ errorMessage }}</p>
    <p v-if="status === 'success'" class="success">Submitted successfully!</p>
    
    <button type="submit" :disabled="status === 'loading'">
      {{ status === 'loading' ? 'Submitting...' : 'Submit' }}
    </button>
  </form>
</template>

Node.js (Server-side)

For server-side file handling, parse the multipart form data and forward it to Forminit:

import express from 'express';
import multer from 'multer';
import { Forminit } from 'forminit';

const app = express();
const upload = multer({ storage: multer.memoryStorage() });

const forminit = new Forminit({
  apiKey: process.env.FORMINIT_API_KEY,
});

const FORM_ID = 'YOUR_FORM_ID';

app.post('/submit', upload.fields([
  { name: 'resume', maxCount: 1 },
  { name: 'documents', maxCount: 5 }
]), async (req, res) => {
  const formData = new FormData();
  
  // Add sender fields
  formData.append('fi-sender-firstName', req.body.firstName);
  formData.append('fi-sender-lastName', req.body.lastName);
  formData.append('fi-sender-email', req.body.email);
  
  // Add file fields
  if (req.files.resume) {
    const file = req.files.resume[0];
    formData.append('fi-file-resume', new Blob([file.buffer]), file.originalname);
  }
  
  if (req.files.documents) {
    for (const file of req.files.documents) {
      formData.append('fi-file-documents', new Blob([file.buffer]), file.originalname);
    }
  }
  
  const { data, error } = await forminit.submit(FORM_ID, formData);
  
  if (error) {
    return res.status(400).json({ success: false, message: error.message });
  }
  
  res.json({ success: true, submissionId: data.hashId });
});

app.listen(3000);

Drag and Drop Upload

Create a custom drag-and-drop upload experience:

<form id="upload-form">
  <input type="text" name="fi-sender-fullName" placeholder="Your name" required />
  <input type="email" name="fi-sender-email" placeholder="Email" required />
  
  <div id="drop-zone">
    <p>Drag files here or click to browse</p>
    <input type="file" name="fi-file-attachments[]" id="file-input" multiple hidden />
  </div>
  <ul id="file-list"></ul>
  
  <button type="submit">Upload</button>
</form>

<script src="https://forminit.com/sdk/v1/forminit.js"></script>
<script>
  const dropZone = document.getElementById('drop-zone');
  const fileInput = document.getElementById('file-input');
  const fileList = document.getElementById('file-list');
  
  // Click to browse
  dropZone.addEventListener('click', () => fileInput.click());
  
  // Drag and drop handlers
  dropZone.addEventListener('dragover', (e) => {
    e.preventDefault();
    dropZone.classList.add('drag-over');
  });
  
  dropZone.addEventListener('dragleave', () => {
    dropZone.classList.remove('drag-over');
  });
  
  dropZone.addEventListener('drop', (e) => {
    e.preventDefault();
    dropZone.classList.remove('drag-over');
    
    const dt = new DataTransfer();
    for (const file of e.dataTransfer.files) {
      dt.items.add(file);
    }
    fileInput.files = dt.files;
    updateFileList();
  });
  
  fileInput.addEventListener('change', updateFileList);
  
  function updateFileList() {
    fileList.innerHTML = '';
    for (const file of fileInput.files) {
      const li = document.createElement('li');
      li.textContent = `${file.name} (${(file.size / 1024).toFixed(1)} KB)`;
      fileList.appendChild(li);
    }
  }
  
  // Form submission
  const forminit = new Forminit();
  const FORM_ID = 'YOUR_FORM_ID';
  
  document.getElementById('upload-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    
    const formData = new FormData(e.target);
    const { data, error } = await forminit.submit(FORM_ID, formData);
    
    if (error) {
      alert(error.message);
      return;
    }
    
    alert('Files uploaded successfully!');
    e.target.reset();
    fileList.innerHTML = '';
  });
</script>

<style>
  #drop-zone {
    border: 2px dashed #ccc;
    padding: 40px;
    text-align: center;
    cursor: pointer;
    transition: border-color 0.2s, background-color 0.2s;
  }
  
  #drop-zone.drag-over {
    border-color: #007bff;
    background-color: #f0f7ff;
  }
  
  #file-list {
    list-style: none;
    padding: 0;
    margin: 10px 0;
  }
  
  #file-list li {
    padding: 5px 10px;
    background: #f5f5f5;
    margin: 5px 0;
    border-radius: 4px;
  }
</style>

Response Structure

When a submission with files succeeds, the response includes file information in the blocks:

{
  "success": true,
  "redirectUrl": "https://forminit.com/thank-you",
  "submission": {
    "hashId": "abc123xyz",
    "date": "2025-01-15 14:30:00",
    "blocks": {
      "sender": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
      },
      "resume": {
        "filename": "john-doe-resume.pdf",
        "size": 245678,
        "type": "application/pdf"
      },
      "attachments": [
        {
          "filename": "portfolio-1.jpg",
          "size": 102400,
          "type": "image/jpeg"
        },
        {
          "filename": "portfolio-2.jpg",
          "size": 98304,
          "type": "image/jpeg"
        }
      ]
    }
  }
}

Best Practices

Client-side Validation

Validate files before submission to improve user experience:

const MAX_TOTAL_SIZE = 25 * 1024 * 1024; // 25 MB per submission

function validateFile(file, options = {}) {
  const {
    maxSize = 10 * 1024 * 1024, // 10MB default per file
    allowedTypes = [],
    allowedExtensions = []
  } = options;
  
  const errors = [];
  
  // Check file size
  if (file.size > maxSize) {
    errors.push(`File "${file.name}" exceeds maximum size of ${maxSize / 1024 / 1024}MB`);
  }
  
  // Check MIME type
  if (allowedTypes.length > 0 && !allowedTypes.includes(file.type)) {
    errors.push(`File "${file.name}" has invalid type. Allowed: ${allowedTypes.join(', ')}`);
  }
  
  // Check extension
  if (allowedExtensions.length > 0) {
    const ext = file.name.split('.').pop().toLowerCase();
    if (!allowedExtensions.includes(ext)) {
      errors.push(`File "${file.name}" has invalid extension. Allowed: ${allowedExtensions.join(', ')}`);
    }
  }
  
  return errors;
}

// Validate total submission size (25 MB limit)
function validateTotalSize(files) {
  const totalSize = Array.from(files).reduce((sum, file) => sum + file.size, 0);
  
  if (totalSize > MAX_TOTAL_SIZE) {
    const totalMB = (totalSize / 1024 / 1024).toFixed(2);
    return `Total file size (${totalMB} MB) exceeds the 25 MB limit per submission.`;
  }
  
  return null;
}

// Usage
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', () => {
  // Check individual files
  for (const file of fileInput.files) {
    const errors = validateFile(file, {
      maxSize: 5 * 1024 * 1024, // 5MB per file
      allowedExtensions: ['pdf', 'doc', 'docx']
    });
    
    if (errors.length > 0) {
      alert(errors.join('\n'));
      fileInput.value = '';
      return;
    }
  }
  
  // Check total size across all file inputs
  const allFileInputs = document.querySelectorAll('input[type="file"]');
  const allFiles = Array.from(allFileInputs).flatMap(input => Array.from(input.files));
  
  const totalError = validateTotalSize(allFiles);
  if (totalError) {
    alert(totalError);
    fileInput.value = '';
  }
});

Show Upload Progress

For large files, display upload progress:

async function submitWithProgress(formId, formData, onProgress) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    
    xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) {
        const percent = Math.round((e.loaded / e.total) * 100);
        onProgress(percent);
      }
    });
    
    xhr.addEventListener('load', () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        resolve(JSON.parse(xhr.responseText));
      } else {
        reject(new Error(xhr.statusText));
      }
    });
    
    xhr.addEventListener('error', () => reject(new Error('Upload failed')));
    
    xhr.open('POST', `https://forminit.com/f/${formId}`);
    xhr.send(formData);
  });
}

// Usage
const progressBar = document.getElementById('progress-bar');

submitWithProgress('YOUR_FORM_ID', formData, (percent) => {
  progressBar.style.width = `${percent}%`;
  progressBar.textContent = `${percent}%`;
}).then((response) => {
  console.log('Upload complete:', response);
}).catch((error) => {
  console.error('Upload failed:', error);
});

Clear File Input After Submission

Always reset file inputs after successful submission:

// Using form.reset()
form.reset();

// Or manually clear file input
document.querySelector('input[type="file"]').value = '';

Accepted File Types

Forminit accepts the following file types. Use the MIME type in your accept attribute for precise control, or use extensions for simplicity.

Documents

MIME Type	Extension(s)	Description
`application/pdf`	`.pdf`	PDF documents
`application/msword`	`.doc`	Microsoft Word (legacy)
`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`	Microsoft Word
`application/vnd.ms-powerpoint`	`.ppt`	Microsoft PowerPoint (legacy)
`application/vnd.openxmlformats-officedocument.presentationml.presentation`	`.pptx`	Microsoft PowerPoint
`application/vnd.ms-excel`	`.xls`	Microsoft Excel (legacy)
`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`	Microsoft Excel
`text/csv`	`.csv`	CSV spreadsheet
`application/rtf`	`.rtf`	Rich Text Format
`text/html`	`.html`, `.htm`	HTML documents
`text/plain`	`.txt`, `.sketch`	Plain text
`application/xml`	`.xml`	XML documents
`application/epub+zip`	`.epub`	EPUB ebook
`application/vnd.amazon.ebook`	`.azw`	Amazon Kindle ebook
`application/x-mobipocket-ebook`	`.mobi`	Mobipocket ebook

Images

MIME Type	Extension(s)	Description
`image/jpeg`	`.jpg`, `.jpeg`	JPEG image
`image/png`	`.png`	PNG image
`image/gif`	`.gif`	GIF image
`image/webp`	`.webp`	WebP image
`image/tiff`	`.tif`, `.tiff`	TIFF image
`image/heic`	`.heic`	HEIC image (Apple)
`image/svg+xml`	`.svg`	SVG vector
`image/vnd.adobe.photoshop`	`.psd`	Adobe Photoshop
`application/x-photoshop`	`.psd`	Adobe Photoshop
`application/photoshop`	`.psd`	Adobe Photoshop
`application/psd`	`.psd`	Adobe Photoshop
`image/psd`	`.psd`	Adobe Photoshop
`application/postscript`	`.ai`, `.ps`, `.eps`	Adobe Illustrator / PostScript

Audio

MIME Type	Extension(s)	Description
`audio/mp3`	`.mp3`	MP3 audio
`audio/mpeg`	`.mp3`	MP3 audio
`video/mpeg3`	`.mp3`	MP3 audio
`audio/x-ms-wma`	`.wma`	Windows Media Audio
`audio/webm`	`.webm`	WebM audio

Video

MIME Type	Extension(s)	Description
`video/mp4`	`.mp4`	MP4 video
`video/webm`	`.webm`	WebM video
`video/x-flv`	`.flv`	Flash video
`video/avi`	`.avi`	AVI video
`video/quicktime`	`.mov`	QuickTime video
`application/x-lotusscreencam`	`.scm`	Screen recording

MIME Type	Extension(s)	Description
`application/zip`	`.zip`	ZIP archive
`application/x-zip`	`.zip`	ZIP archive
`application/x-compressed-rar`	`.rar`	RAR archive
`application/x-rar`	`.rar`	RAR archive
`application/x-tar`	`.tar`	TAR archive
`application/x-7z-compressed`	`.7z`	7-Zip archive
`application/octet-stream`	`.zip`, `.rar`	Binary file

Apple iWork

MIME Type	Extension(s)	Description
`application/x-iwork-keynote-sffkey`	`.key`	Apple Keynote
`application/x-iwork-pages-sffpages`	`.pages`	Apple Pages
`application/x-iwork-numbers-sffnumbers`	`.numbers`	Apple Numbers

Using Accept Attribute

By extension (simple):

<input type="file" name="fi-file-document" accept=".pdf,.doc,.docx" />

By MIME type (precise):

<input type="file" name="fi-file-document" accept="application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" />

By category:

<!-- All images -->
<input type="file" name="fi-file-photo" accept="image/*" />

<!-- All videos -->
<input type="file" name="fi-file-video" accept="video/*" />

<!-- All audio -->
<input type="file" name="fi-file-audio" accept="audio/*" />

Common combinations:

<!-- Documents only -->
<input type="file" name="fi-file-doc" accept=".pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.csv,.rtf,.txt" />

<!-- Images only -->
<input type="file" name="fi-file-image" accept=".jpg,.jpeg,.png,.gif,.webp,.svg,.heic" />

<!-- Media files -->
<input type="file" name="fi-file-media" accept=".mp3,.mp4,.mov,.avi,.webm" />

<!-- Archives -->
<input type="file" name="fi-file-archive" accept=".zip,.rar,.7z,.tar" />

Limitations

Limit	Value
Maximum upload size per submission	25 MB
Content type	Must use `multipart/form-data`
JSON support	Not supported for file uploads
Maximum files per block	No fixed count; every file in the submission shares the 25 MB limit
Maximum file blocks	20 per submission
Maximum field blocks (all types, including file blocks)	100 per submission, up to 50 of the same type

Note: The 25 MB limit applies to the total size of all files in a single submission. If you need to upload larger files, consider splitting them across multiple submissions or compressing them before upload.

Common Issues

“File upload requires multipart/form-data”

Make sure you’re using FormData and not JSON:

// ❌ Wrong - JSON doesn't support files
const { data, error } = await forminit.submit(FORM_ID, {
  blocks: [
    { type: 'file', name: 'resume', value: file } // Won't work
  ]
});

// ✅ Correct - Use FormData
const formData = new FormData();
formData.append('fi-file-resume', file);
const { data, error } = await forminit.submit(FORM_ID, formData);

Files not appearing in submission

Check that field names use the correct fi-file-{name} pattern:

<!-- ❌ Wrong -->
<input type="file" name="resume" />
<input type="file" name="file-resume" />

<!-- ✅ Correct -->
<input type="file" name="fi-file-resume" />

Form not submitting files

Ensure the form has the correct enctype if submitting natively:

<!-- Required for native form submission -->
<form action="..." method="POST" enctype="multipart/form-data">
  ...
</form>

When using JavaScript with FormData, the enctype is automatically set.

Submission Retention - Set how long files and their submissions are stored before automatic deletion
Form Blocks Reference - Complete reference for all block types
HTML Integration - Static site setup guide
Next.js Integration - Next.js setup guide

View this page as Markdown

Was this page helpful?