File Upload

Handle file inputs and drag-and-drop upload zones via fields with type: 'file'. The form treats file fields as first-class citizens — they expose the selected FileList, support drop events, and integrate with validation.

🔗 Live Demo: File Upload
📁 Source: FormFileUpload.tsx
📁 Setup: fileUpload.ts

---

Concept

File fields use type: 'file' in the field definition. This tells the form to store a FileList or dropped files instead of a plain string/number value. The field.files property exposes the selected files, and the onDrop hook handles drag-and-drop events.

---

Form Setup

Two file fields — one for a standard file input, one for a drag-and-drop zone:

const fields = {
  myFileUpload: {
    type: 'file',
    hooks: {
      onDrop: field => console.log('onDrop', field.files),
    },
  },
  myDropZone: {
    type: 'file',
    hooks: {
      onDrop: field => console.log('onDrop', field.files),
    },
  },
};

Both fields share the same onDrop hook, but in a real application you would:

• Read the file(s) with FileReader for preview
• Upload them to a server
• Set custom validation for file type, size, or count

---

Field Properties for File Fields

field.files

Returns the current FileList (or array of dropped files). This is the primary way to access uploaded files programmatically.

type: 'file'

Tells the form that this field stores file data. When set, field.value will be a reference to the file object or null.

onDrop hook

Fired when files are dropped onto a drag-and-drop zone. The hook receives the field instance and the drag event:

hooks: {
  myDropZone: {
    onDrop(field, e) {
      // field.files now contains the dropped files
      const files = Array.from(field.files);
      console.log(files.map(f => f.name));
    },
  },
}

---

Component Walkthrough

The demo renders two file upload areas side by side:

Standard file input

Uses a native <input type="file"> bound via field.bind(). The multiple attribute allows selecting several files at once:

<input
  {...field.bind()}
  type="file"
  multiple
  className="form-input file:mr-4 file:py-2 file:px-4 file:rounded-lg file:border-0 file:bg-brand-50 file:text-brand-700"
/>

Drag-and-drop zone

A styled <div> that accepts file drops. The onDrop event handler is attached via the field's hooks.onDrop:

<div
  onDragOver={(e) => e.preventDefault()}
  onDrop={(e) => {
    e.preventDefault();
    field.hooks.onDrop(field, e);
  }}
  className="drop-zone"
>
  <Upload size={24} />
  <p>Drop files here</p>
</div>

---

Validation with File Fields

File fields can be validated like any other field. Add rules to enforce file requirements:

const fields = {
  avatar: {
    type: 'file',
    label: 'Profile Picture',
    rules: 'required',
    hooks: {
      onChange(field) {
        const file = field.files?.[0];
        if (file) {
          // Client-side validation
          if (!file.type.startsWith('image/')) {
            field.invalidate('Only image files are allowed');
          }
          if (file.size > 5 * 1024 * 1024) {
            field.invalidate('File must be less than 5MB');
          }
        }
      },
    },
  },
};

---

Reading file contents

Use the FileReader API to read file contents (e.g., for image preview):

hooks: {
  onDrop(field) {
    const file = field.files[0];
    if (file) {
      const reader = new FileReader();
      reader.onload = (e) => {
        field.set('extra', {
          previewUrl: e.target.result,
          fileName: file.name,
          fileSize: file.size,
        });
      };
      reader.readAsDataURL(file);
    }
  },
},

---

Key Takeaways

1. type: 'file': Declares a field as a file uploader — stores File objects instead of strings.
2. field.files: Access the selected/dropped file list from any file field.
3. onDrop hook: Handle drag-and-drop events declaratively in the field definition.
4. Validation works: Add rules and custom validation to enforce file type, size, or count.
5. FileReader for preview: Combine with FileReader to show image previews or parse uploaded data.
6. Two modes: Standard <input type="file"> for click-to-browse, or custom drop zone for drag-and-drop.