File Upload

Easy Forms provides a modern drag-and-drop file upload component with multiple file support, file removal, and size display.

Basic File Upload

Simple file upload field.

Statamic Field Configuration:

• Field Type: Assets

Example:

handle: resume
field:
  type: assets
  display: Upload Resume
  max_files: 1
  validate: required

Features

• Drag-and-drop interface
• Click to browse
• Multiple file support
• File removal capability
• File size display
• Type validation
• Size validation
• Preview thumbnails (images)
• Progress indication

Configuration Options

Maximum Files

Limit the number of files:

handle: documents
field:
  type: assets
  display: Upload Documents
  max_files: 5
  validate: required

Single File

Restrict to one file only:

handle: profile_photo
field:
  type: assets
  display: Profile Photo
  max_files: 1
  validate: required

Allowed File Types

Restrict file types by MIME type or extension:

handle: resume
field:
  type: assets
  display: Resume
  max_files: 1
  allowed_extensions:
    - pdf
    - doc
    - docx
  validate: required|mimes:pdf,doc,docx

Common File Type Groups:

Images:

allowed_extensions:
  - jpg
  - jpeg
  - png
  - gif
  - webp

Documents:

allowed_extensions:
  - pdf
  - doc
  - docx
  - txt

Spreadsheets:

allowed_extensions:
  - xls
  - xlsx
  - csv

Archives:

allowed_extensions:
  - zip
  - rar
  - tar
  - gz

Maximum File Size

Limit individual file size:

handle: photo
field:
  type: assets
  display: Photo
  max_files: 1
  max_size: 5120  # in KB (5MB)
  validate: required|max:5120

Minimum File Size

Set minimum file size:

handle: photo
field:
  type: assets
  display: High Resolution Photo
  max_files: 1
  min_size: 1024  # in KB (1MB)
  validate: required|min:1024

Container Configuration

Specify which asset container to use:

handle: documents
field:
  type: assets
  display: Documents
  container: uploads
  max_files: 5
  validate: required

Validation

Required Upload

Require at least one file:

handle: document
field:
  type: assets
  display: Required Document
  validate: required

File Type Validation

Validate by MIME type:

handle: photo
field:
  type: assets
  display: Photo
  validate: required|mimes:jpeg,jpg,png|max:5120

Image Dimension Validation

Validate image dimensions:

handle: banner
field:
  type: assets
  display: Banner Image
  max_files: 1
  validate: required|image|dimensions:min_width=1200,min_height=400

Multiple Validations

Combine multiple rules:

handle: profile_photo
field:
  type: assets
  display: Profile Photo
  max_files: 1
  validate: |
    required
    image
    mimes:jpeg,jpg,png
    max:2048
    dimensions:min_width=200,min_height=200,max_width=2000,max_height=2000

Display Options

Show File Size

Display file sizes:

handle: documents
field:
  type: assets
  display: Documents
  show_size: true
  max_files: 5

Show File Type

Display file type icons:

handle: documents
field:
  type: assets
  display: Documents
  show_type: true
  max_files: 5

Image Previews

Show thumbnail previews for images:

handle: photos
field:
  type: assets
  display: Photos
  show_preview: true
  max_files: 10

Styling & Customization

The file upload component is styled with Tailwind CSS.

Custom Upload Area

Customize the drag-and-drop area:

handle: documents
field:
  type: assets
  display: Documents
  upload_text: Drop files here or click to browse
  max_files: 5

Custom Button Text

Customize the browse button:

handle: documents
field:
  type: assets
  display: Documents
  button_text: Choose Files
  max_files: 5

Accessibility

File upload includes:

• Keyboard navigation
• Screen reader support
• Focus indicators
• ARIA labels
• Clear upload status
• Error announcements

Keyboard Navigation

• Tab: Focus upload area
• Enter/Space: Open file browser
• Escape: Cancel upload
• Tab through uploaded files
• Delete key: Remove focused file

Best Practices

File Types

• Clearly communicate accepted types
• Validate on both client and server
• Provide helpful error messages
• Use appropriate extensions

File Size

• Set reasonable size limits
• Display size limits clearly
• Compress images when possible
• Consider user connection speed

Multiple Files

• Show progress for each file
• Allow individual file removal
• Display total size
• Limit reasonable number

User Experience

• Provide clear instructions
• Show upload progress
• Display success/error states
• Allow easy file replacement

Security

• Validate file types server-side
• Scan for malware
• Limit file sizes
• Use secure storage

Examples

Profile Photo Upload

handle: profile_photo
field:
  type: assets
  display: Profile Photo
  max_files: 1
  allowed_extensions:
    - jpg
    - jpeg
    - png
  max_size: 2048
  show_preview: true
  validate: required|image|mimes:jpeg,jpg,png|max:2048

Resume Upload

handle: resume
field:
  type: assets
  display: Upload Resume (PDF only)
  max_files: 1
  allowed_extensions:
    - pdf
  max_size: 5120
  validate: required|mimes:pdf|max:5120

Document Upload (Multiple)

handle: supporting_documents
field:
  type: assets
  display: Supporting Documents
  max_files: 10
  allowed_extensions:
    - pdf
    - doc
    - docx
    - jpg
    - png
  max_size: 10240
  show_size: true
  show_type: true
  validate: required|max:10240

Photo Gallery

handle: photos
field:
  type: assets
  display: Photos (up to 20)
  max_files: 20
  allowed_extensions:
    - jpg
    - jpeg
    - png
  max_size: 5120
  show_preview: true
  upload_text: Drop photos here or click to browse
  validate: required|image|max:5120

Logo Upload

handle: company_logo
field:
  type: assets
  display: Company Logo
  max_files: 1
  allowed_extensions:
    - png
    - svg
  max_size: 1024
  show_preview: true
  validate: |
    required
    image
    mimes:png,svg
    max:1024
    dimensions:min_width=200,min_height=200