or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

drag-drop.md index.md modify-upload.md upload-component.md

tile.json

Drag & Drop Utilities

The create_drag utility provides reusable drag-and-drop functionality for creating custom file upload interfaces. It handles all aspects of drag-and-drop interactions including visual feedback, file validation, and multiple upload modes.

Capabilities

create_drag Function

Creates a complete drag-and-drop system with configurable options and programmatic file picker access.

/**
 * Creates drag-and-drop functionality for file uploads
 * @returns Object with drag action and file picker function
 */
function create_drag(): {
  drag: (node: HTMLElement, options: DragActionOptions) => ActionReturn;
  open_file_upload: () => void;
};

Drag Action

The drag function is a Svelte action that adds comprehensive drag-and-drop functionality to any HTML element:

/**
 * Svelte action for adding drag-and-drop functionality to DOM elements
 * @param node - HTML element to attach drag-and-drop to
 * @param options - Configuration options for drag behavior
 * @returns Action return object with update and destroy methods
 */
function drag(node: HTMLElement, options: DragActionOptions): ActionReturn;

// Action return interface for Svelte actions
interface ActionReturn {
  /** Update drag options dynamically */
  update: (new_options: DragActionOptions) => void;
  /** Remove all event listeners and cleanup */
  destroy: () => void;
}

Drag Action Options

Configuration interface for customizing drag-and-drop behavior:

interface DragActionOptions {
  /** Disable click-to-upload functionality */
  disable_click?: boolean;
  /** Accepted file types (string, array, or null for any) */
  accepted_types?: string | string[] | null;
  /** Upload mode - single file, multiple files, or directory */
  mode?: "single" | "multiple" | "directory";
  /** Callback fired when drag state changes */
  on_drag_change?: (dragging: boolean) => void;
  /** Callback fired when files are selected or dropped */
  on_files?: (files: File[]) => void;
}

File Picker Function

Programmatically trigger the file picker dialog:

/**
 * Programmatically open the file picker dialog
 * Uses the last configured options from the drag action
 */
function open_file_upload(): void;

Usage Examples:

import { create_drag } from "@gradio/upload";

// Create drag system
const { drag, open_file_upload } = create_drag();

// Basic drag-and-drop setup
let dragElement;
let isDragging = false;

// In Svelte component
<div
  bind:this={dragElement}
  use:drag={{
    accepted_types: ["image", "video"],
    mode: "multiple",
    on_drag_change: (dragging) => {
      isDragging = dragging;
    },
    on_files: (files) => {
      console.log("Files received:", files);
      handleFileUpload(files);
    }
  }}
  class:dragging={isDragging}
>
  Drop files here or click to browse
</div>

// Programmatic file picker
<button on:click={open_file_upload}>
  Choose Files
</button>

Upload Modes

The mode option controls file selection behavior:

// Single file selection
mode: "single"
// - File input allows single file selection
// - Returns array with one file maximum

// Multiple file selection  
mode: "multiple"
// - File input allows multiple file selection
// - Returns array with multiple files

// Directory selection
mode: "directory"
// - File input allows directory selection
// - Returns array with all files in selected directory
// - Sets webkitdirectory, directory, and mozdirectory attributes

File Type Acceptance

The accepted_types option supports various formats:

// Single type
accepted_types: "image"        // Accepts image/*
accepted_types: ".pdf"         // Accepts .pdf files
accepted_types: "image/jpeg"   // Accepts only JPEG

// Multiple types
accepted_types: ["image", "video"]           // image/* and video/*
accepted_types: [".pdf", ".doc", ".docx"]   // Specific extensions
accepted_types: ["image/jpeg", "image/png"] // Specific MIME types

// Any files
accepted_types: null           // No restrictions
accepted_types: "*"            // No restrictions
accepted_types: "file/*"       // No restrictions

Event Handling

The drag action handles all standard drag-and-drop events:

dragenter: Visual feedback when drag enters the drop zone
dragleave: Visual feedback when drag leaves the drop zone
dragover: Prevent default to allow dropping
drop: Process dropped files and call on_files callback
click: Open file picker when disable_click is false

Dynamic Updates

Options can be updated dynamically using the returned update function:

let dragAction;

// Initial setup
<div use:drag={dragAction}></div>

// Update options dynamically
function updateDragOptions() {
  dragAction = {
    accepted_types: ["image"],
    mode: "single",
    on_files: handleSingleImage
  };
}

Cleanup

The action automatically cleans up all event listeners when the component is destroyed or the action is removed. Manual cleanup can be triggered using the destroy method:

const actionReturn = drag(element, options);
// Later...
actionReturn.destroy();

Hidden File Input

The drag action creates a hidden file input element with proper configuration:

Type set to "file"
Accepts attribute set based on accepted_types
Multiple attribute set based on mode
Directory attributes set for directory mode
Properly accessible with ARIA labels

Integration with Upload Component

The create_drag utility is used internally by the Upload component but can also be used independently for custom upload interfaces:

// Custom upload component using create_drag
import { create_drag } from "@gradio/upload";

const { drag, open_file_upload } = create_drag();

<div
  use:drag={{
    accepted_types: fileTypes,
    mode: uploadMode,
    disable_click: disableClick,
    on_drag_change: (dragging) => setDragging(dragging),
    on_files: processFiles
  }}
  class="custom-upload-area"
>
  <slot />
</div>