Drag UI - File Upload Component Library

A highly customizable, accessible, and config-driven file upload component library built with React, TypeScript, and Tailwind CSS.

Website • Documentation • GitHub Developer

Features

• Beautiful Color Themes - Emerald, Blue, Purple, Orange, Rose, and Slate with gradient backgrounds
• Component Variants - Dropzone, Button, Compact, Preview, and Image-focused layouts
• JSON Configuration - LLM-friendly, declarative configuration system
• Fully Accessible - WCAG compliant with keyboard navigation and screen reader support
• Responsive Design - Mobile-first approach with touch-friendly interfaces
• TypeScript Ready - Complete type safety and excellent developer experience
• Real-time Theme Switching - Change colors instantly with built-in color picker
• Progress Tracking - Visual upload progress with customizable indicators
• Image Previews - Automatic image thumbnails with proper memory management
• Internationalization - Multi-language support with customizable labels

Quick Start

Installation

npm install @drag-ui/drag-ui
# or
yarn add @drag-ui/drag-ui
# or
pnpm add @drag-ui/drag-ui

Basic Usage

import { FileUpload } from '@drag-ui/drag-ui'

function App() {
  const handleFilesChange = (files: File[]) => {
    console.log('Selected files:', files)
  }

  const handleError = (error: string) => {
    console.error('Upload error:', error)
  }

  return (
    <FileUpload
      config={{
        variant: "dropzone",
        colorTheme: "emerald",
        maxFileSize: 10 * 1024 * 1024, // 10MB
        maxFiles: 5,
        acceptedFileTypes: ["image/*", ".pdf", ".doc", ".docx"],
        showColorPicker: true
      }}
      onFilesChange={handleFilesChange}
      onError={handleError}
    />
  )
}

Component Variants

1. Dropzone (Default)

Classic drag-and-drop interface with large drop area and file previews.

<FileUpload config={{ variant: "dropzone" }} />

2. Button

Simple button-style upload for minimal interfaces.

<FileUpload config={{ variant: "button" }} />

3. Compact

Space-efficient horizontal layout perfect for forms.

<FileUpload config={{ variant: "compact" }} />

4. Preview

Full-featured interface with detailed file management.

<FileUpload config={{ variant: "preview" }} />

5. Image

Optimized for image uploads with thumbnail previews.

<FileUpload config={{ variant: "image" }} />

Color Themes

Choose from 6 beautiful color themes:

• Emerald - Fresh green with nature-inspired gradients
• Blue - Classic professional blue theme
• Purple - Creative purple with modern gradients
• Orange - Energetic orange with warm tones
• Rose - Elegant rose with soft pink accents
• Slate - Neutral theme for professional interfaces

<FileUpload 
  config={{ 
    colorTheme: "purple",
    showColorPicker: true // Allow users to switch themes
  }} 
/>

JSON Configuration

Drag UI uses a simple, flat JSON structure that's perfect for LLMs, CMSs, and dynamic applications:

{
  "variant": "dropzone",
  "colorTheme": "emerald",
  "size": "md",
  "radius": "lg",
  "maxFileSize": 10485760,
  "maxFiles": 5,
  "acceptedFileTypes": ["image/*", ".pdf", ".doc", ".docx"],
  "labels": {
    "uploadText": "Upload your files",
    "dragText": "Drag and drop files here, or click to browse",
    "browseText": "Browse Files",
    "errorText": "Upload failed",
    "successText": "Upload successful"
  },
  "showProgress": true,
  "showPreview": true,
  "showColorPicker": true,
  "disabled": false
}

Configuration Presets

Use pre-built configurations for common scenarios:

import { dragUIConfig } from '@drag-ui/drag-ui/config'

// Load a preset
const config = dragUIConfig.presets.imageGallery
<FileUpload config={config} />

Available presets:

• minimal - Simple button upload
• standard - Default dropzone with all features
• advanced - Full-featured preview with large file support
• imageGallery - Optimized for image collections
• documentUpload - Compact design for documents

API Reference

FileUploadProps

Property	Type	Description
config	FileUploadConfig	Configuration object
onFilesChange	(files: File[]) => void	Called when files change
onError	(error: string) => void	Called on validation errors
onColorChange	(theme: ColorTheme) => void	Called when theme changes
value	File[]	Controlled file list
className	string	Additional CSS classes

FileUploadConfig

Property	Type	Default	Description
variant	"dropzone" | "button" | "compact" | "preview" | "image"	"dropzone"	Component style
colorTheme	"emerald" | "blue" | "purple" | "orange" | "rose" | "slate"	"emerald"	Color theme
size	"sm" | "md" | "lg"	"md"	Component size
radius	"none" | "sm" | "md" | "lg" | "xl" | "full"	"lg"	Border radius
maxFileSize	number	10485760 (10MB)	Max file size in bytes
maxFiles	number	5	Maximum number of files
acceptedFileTypes	string[]	["image/*", ".pdf"]	Accepted file types
showProgress	boolean	true	Show upload progress
showPreview	boolean	true	Show file previews
showColorPicker	boolean	true	Show theme picker
disabled	boolean	false	Disable component

Accessibility

Drag UI is built with accessibility as a first-class citizen:

• Keyboard Navigation - Full keyboard support with Tab, Enter, and Space
• Screen Reader Support - Proper ARIA labels and descriptions
• Focus Management - Clear focus indicators and logical tab order
• Error Handling - Accessible error messages and validation feedback
• High Contrast - Themes work with high contrast mode
• Reduced Motion - Respects user's motion preferences

Internationalization

Customize labels for different languages:

<FileUpload
  config={{
    labels: {
      uploadText: "Subir archivos",
      dragText: "Arrastra y suelta archivos aquí",
      browseText: "Explorar Archivos",
      errorText: "Error en la subida",
      successText: "Subida exitosa"
    }
  }}
/>

Use Cases

• Image Galleries - Perfect for photo uploads with previews
• Document Management - Handle PDFs, Word docs, and more
• Form Integration - Compact variants for form fields
• Content Management - Full-featured preview for CMS systems
• E-commerce - Product image uploads with validation
• Social Media - Media uploads with progress tracking

Development

Local Development

git clone https://github.com/krishvsoni/drag-ui.git
cd drag-ui
npm install
npm run dev

Building

npm run build
npm run pack

Testing

npm run test
npm run test:coverage

Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

License

MIT © Krish Soni

Acknowledgments

• Radix UI for accessible primitives
• Tailwind CSS for styling system
• Lucide React for beautiful icons
• shadcn/ui for design inspiration

---

<div align="center">
  <p>Built with love for developers who care about accessibility and user experience.</p>
  <p>
    <a href="https://drag-ui.vercel.app">Website</a> •
    <a href="https://drag-ui.vercel.app">Try Demo</a> •
    <a href="https://twitter.com/krishvsoni">Follow Updates</a>
  </p>
</div>