FileKit

Zero-dependency file upload toolkit with drag & drop, chunked transfers, progress tracking, and first-class React support.

Features

• Zero Dependencies - No external runtime dependencies
• TypeScript First - Written in strict TypeScript with complete type definitions
• Small Bundle - Core < 4KB, with React < 6KB (minified + gzipped)
• Drag & Drop - Built-in drop zone with visual feedback
• Chunked Uploads - Upload large files in chunks with parallel transfers
• Progress Tracking - Real-time upload progress with speed and ETA
• Validation - File size, type, and custom validators
• Image Preview - Generate thumbnails and compress images
• React Integration - First-class hooks and components

Installation

npm install @oxog/filekit

Quick Start

Vanilla JavaScript

import { createUploader } from '@oxog/filekit'

const uploader = createUploader({
  endpoint: '/api/upload',
  maxFileSize: 10 * 1024 * 1024, // 10MB
  allowedTypes: ['image/*', 'application/pdf'],
})

uploader.on('progress', (file) => {
  console.log(`${file.name}: ${file.progress}%`)
})

uploader.on('complete', (file) => {
  console.log(`Uploaded: ${file.name}`)
})

// Add files and upload
uploader.addFiles(files)
uploader.uploadAll()

React

import { useUploader, DropZone, FileList } from '@oxog/filekit/react'

function FileUpload() {
  const { files, addFiles, uploadAll, progress, isUploading } = useUploader({
    endpoint: '/api/upload',
    maxFileSize: 10 * 1024 * 1024,
  })

  return (
    <div>
      <DropZone onDrop={addFiles}>
        {({ isDragActive }) => (
          <div>{isDragActive ? 'Drop files here...' : 'Drag files here or click to browse'}</div>
        )}
      </DropZone>

      <FileList files={files} showPreview showProgress />

      <button onClick={uploadAll} disabled={isUploading}>
        {isUploading ? `Uploading... ${progress.percentage}%` : 'Upload All'}
      </button>
    </div>
  )
}

Documentation

Visit filekit.oxog.dev for full documentation.

• Getting Started
• Upload Guide
• Drop Zone
• Validation
• Chunked Upload
• Preview
• React Integration
• API Reference

API Overview

Core Functions

import {
  createUploader,
  createDropZone,
  createValidator,
  createUploadQueue,
} from '@oxog/filekit'

Preview Functions

import {
  createImagePreview,
  getImageDimensions,
  compressImage,
} from '@oxog/filekit'

Utility Functions

import {
  isImage,
  isVideo,
  formatFileSize,
  parseFileSize,
  getFileExtension,
  readAsDataURL,
  readAsText,
} from '@oxog/filekit'

React Hooks

import {
  useUploader,
  useDropZone,
  useFileSelect,
  useImagePreview,
} from '@oxog/filekit/react'

React Components

import {
  DropZone,
  FileInput,
  FileList,
  UploadProgress,
  ImagePreview,
} from '@oxog/filekit/react'

Configuration

Uploader Options

Option	Type	Default	Description
endpoint	string | function	Required	Upload URL
maxFileSize	number	Infinity	Max file size in bytes
allowedTypes	string[]	['*/*']	Allowed MIME types
maxFiles	number	Infinity	Max number of files
autoUpload	boolean	false	Auto upload when files added
sequential	boolean	false	Upload files one at a time
headers	object | function	{}	Custom request headers
withCredentials	boolean	false	Include cookies in requests
retries	number	0	Number of retry attempts
chunked	ChunkedConfig	-	Chunked upload configuration

Chunked Upload Options

Option	Type	Default	Description
enabled	boolean	false	Enable chunked uploads
chunkSize	number	5MB	Size of each chunk
parallel	number	3	Parallel chunk uploads
retries	number	3	Retries per chunk
minSize	number	10MB	Min file size for chunking

Events

Uploader Events

uploader.on('add', (file) => {})
uploader.on('start', (file) => {})
uploader.on('progress', (file) => {})
uploader.on('complete', (file) => {})
uploader.on('error', (file, error) => {})
uploader.on('cancel', (file) => {})
uploader.on('allComplete', () => {})

Drop Zone Events

dropzone.on('drop', (files) => {})
dropzone.on('dragenter', () => {})
dropzone.on('dragleave', () => {})
dropzone.on('error', (error) => {})

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request