tessl/npm-uppy--dashboard

Universal UI plugin for Uppy file uploader providing comprehensive dashboard interface with drag-and-drop, file previews, metadata editing, and progress tracking.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/npm-uppy--dashboard
Author: tessl

Comprehensive configuration options for customizing @uppy/dashboard appearance, behavior, and features.

Capabilities

Dashboard Options Interface

Main configuration interface combining modal/inline options with miscellaneous settings.

/**
 * Main configuration interface for Dashboard plugin
 * Combines modal/inline options with miscellaneous settings
 */
type DashboardOptions<M extends Meta, B extends Body> = 
  DashboardMiscOptions<M, B> & 
  (DashboardModalOptions | DashboardInlineOptions);

Modal Configuration

Options specific to modal (overlay) mode dashboard.

/**
 * Configuration options for modal dashboard mode
 */
interface DashboardModalOptions {
  /** Indicates modal mode (default: false) */
  inline?: false;
  /** Enable open/close animations (default: true) */
  animateOpenClose?: boolean;
  /** Close modal with browser back button (default: false) */
  browserBackButtonClose?: boolean;
  /** Auto-close modal after upload completion (default: false) */
  closeAfterFinish?: boolean;
  /** Close modal when clicking outside (default: false) */
  closeModalOnClickOutside?: boolean;
  /** Disable page scroll when modal open (default: true) */
  disablePageScrollWhenModalOpen?: boolean;
}

Inline Configuration

Options specific to inline (embedded) mode dashboard.

/**
 * Configuration options for inline dashboard mode
 */
interface DashboardInlineOptions {
  /** Indicates inline mode (required: true) */
  inline: true;
  /** Container height in pixels or CSS string (default: 550) */
  height?: string | number;
  /** Container width in pixels or CSS string (default: 750) */
  width?: string | number;
}

UI Configuration Options

Core user interface and appearance settings.

/**
 * UI and appearance configuration options
 */
interface DashboardUIOptions {
  /** Auto-open editor type on file selection */
  autoOpen?: 'metaEditor' | 'imageEditor' | null;
  /** Default picker icon component */
  defaultPickerIcon?: typeof defaultPickerIcon;
  /** Disable all dashboard interactions (default: false) */
  disabled?: boolean;
  /** Disable informer component (default: false) */
  disableInformer?: boolean;
  /** Disable local file selection (default: false) */
  disableLocalFiles?: boolean;
  /** Disable status bar component (default: false) */
  disableStatusBar?: boolean;
  /** Disable thumbnail generation (default: false) */
  disableThumbnailGenerator?: boolean;
  /** UI theme selection (default: 'light') */
  theme?: 'auto' | 'dark' | 'light';
}

Usage Examples:

import Dashboard from "@uppy/dashboard";

// Auto theme with system preference
uppy.use(Dashboard, {
  theme: "auto", // Automatically switches with system preference
  disabled: false,
  disableStatusBar: false
});

// Dark theme with disabled informer
uppy.use(Dashboard, {
  theme: "dark",
  disableInformer: true,
  autoOpen: "metaEditor"
});

File Management Options

Configuration for file selection, display, and management behavior.

/**
 * File management and display configuration
 */
interface DashboardFileOptions<M extends Meta, B extends Body> {
  /** Selection type for file manager */
  fileManagerSelectionType?: 'files' | 'folders' | 'both';
  /** Metadata fields configuration */
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
  /** Show selected files list (default: true) */
  showSelectedFiles?: boolean;
  /** Full screen for single file (default: true) */
  singleFileFullScreen?: boolean;
  /** Wait for thumbnails before upload (default: false) */
  waitForThumbnailsBeforeUpload?: boolean;
}

Usage Examples:

// Static metadata fields
uppy.use(Dashboard, {
  metaFields: [
    { id: "name", name: "Name", placeholder: "Enter file name" },
    { id: "caption", name: "Caption" }
  ],
  fileManagerSelectionType: "both"
});

// Dynamic metadata fields based on file type
uppy.use(Dashboard, {
  metaFields: (file) => {
    if (file.type?.startsWith("image/")) {
      return [
        { id: "alt", name: "Alt Text", placeholder: "Describe the image" },
        { id: "title", name: "Title" }
      ];
    }
    return [{ id: "description", name: "Description" }];
  }
});

Button Visibility Options

Control visibility of various UI buttons and elements.

/**
 * Button visibility configuration options
 */
interface DashboardButtonOptions {
  /** Hide cancel button (default: false) */
  hideCancelButton?: boolean;
  /** Hide pause/resume button (default: false) */
  hidePauseResumeButton?: boolean;
  /** Hide progress after completion (default: false) */
  hideProgressAfterFinish?: boolean;
  /** Hide retry button (default: false) */
  hideRetryButton?: boolean;
  /** Hide upload button (default: false) */
  hideUploadButton?: boolean;
  /** Hide detailed progress information (default: false) */
  hideProgressDetails?: boolean;
  /** Show link to upload result (default: false) */
  showLinkToFileUploadResult?: boolean;
  /** Show native photo camera button (default: false) */
  showNativePhotoCameraButton?: boolean;
  /** Show native video camera button (default: false) */
  showNativeVideoCameraButton?: boolean;
  /** Show remove button after completion (default: false) */
  showRemoveButtonAfterComplete?: boolean;
}

Thumbnail Configuration

Options for thumbnail generation and display.

/**
 * Thumbnail generation and display configuration
 */
interface DashboardThumbnailOptions {
  /** Thumbnail height in pixels */
  thumbnailHeight?: number;
  /** Thumbnail MIME type (default: 'image/jpeg') */
  thumbnailType?: string;
  /** Thumbnail width in pixels (default: 280) */
  thumbnailWidth?: number;
}

Event Callback Configuration

Configure event handlers for user interactions and lifecycle events.

/**
 * Event callback configuration options
 */
interface DashboardCallbackOptions {
  /** Done button click handler (null disables button) */
  doneButtonHandler?: null | (() => void);
  /** Drag leave event handler */
  onDragLeave?: (event: DragEvent) => void;
  /** Drag over event handler */
  onDragOver?: (event: DragEvent) => void;
  /** Drop event handler */
  onDrop?: (event: DragEvent) => void;
  /** Modal close request handler */
  onRequestCloseModal?: () => void;
}

Usage Examples:

uppy.use(Dashboard, {
  // Custom done button behavior
  doneButtonHandler: () => {
    console.log("Upload completed!");
    // Custom cleanup or navigation logic
  },
  
  // Custom drag and drop handlers
  onDragOver: (event) => {
    console.log("Files being dragged over dashboard");
  },
  
  onDrop: (event) => {
    console.log("Files dropped on dashboard");
  }
});

Camera and Device Options

Configuration for native device camera integration.

/**
 * Camera and native device configuration
 */
interface DashboardCameraOptions {
  /** Native camera facing mode */
  nativeCameraFacingMode?: 'user' | 'environment' | '';
}

Additional Options

Miscellaneous configuration options for plugins, triggers, and localization.

/**
 * Additional configuration options
 */
interface DashboardMiscOptions {
  /** Note text to display in dashboard */
  note?: string | null;
  /** Array of plugin IDs to include */
  plugins?: string[];
  /** Show "powered by Uppy" text (default: true) */
  proudlyDisplayPoweredByUppy?: boolean;
  /** Element/selector to trigger modal opening */
  trigger?: string | Element | null;
  /** Localization strings */
  locale?: LocaleStrings<typeof locale>;
}

Complete Options Interface

The complete miscellaneous options interface combining all configuration categories.

/**
 * Complete miscellaneous options interface
 * Extends UIPluginOptions from @uppy/core
 */
interface DashboardMiscOptions<M extends Meta, B extends Body> extends UIPluginOptions {
  // UI Options
  autoOpen?: 'metaEditor' | 'imageEditor' | null;
  defaultPickerIcon?: typeof defaultPickerIcon;
  disabled?: boolean;
  disableInformer?: boolean;
  disableLocalFiles?: boolean;
  disableStatusBar?: boolean;
  disableThumbnailGenerator?: boolean;
  theme?: 'auto' | 'dark' | 'light';
  
  // File Management
  fileManagerSelectionType?: 'files' | 'folders' | 'both';
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
  showSelectedFiles?: boolean;
  singleFileFullScreen?: boolean;
  waitForThumbnailsBeforeUpload?: boolean;
  
  // Button Visibility
  hideCancelButton?: boolean;
  hidePauseResumeButton?: boolean;
  hideProgressAfterFinish?: boolean;
  hideRetryButton?: boolean;
  hideUploadButton?: boolean;
  hideProgressDetails?: boolean;
  showLinkToFileUploadResult?: boolean;
  showNativePhotoCameraButton?: boolean;
  showNativeVideoCameraButton?: boolean;
  showRemoveButtonAfterComplete?: boolean;
  
  // Thumbnails
  thumbnailHeight?: number;
  thumbnailType?: string;
  thumbnailWidth?: number;
  
  // Event Callbacks
  doneButtonHandler?: null | (() => void);
  onDragLeave?: (event: DragEvent) => void;
  onDragOver?: (event: DragEvent) => void;
  onDrop?: (event: DragEvent) => void;
  onRequestCloseModal?: () => void;
  
  // Camera
  nativeCameraFacingMode?: 'user' | 'environment' | '';
  
  // Miscellaneous  
  note?: string | null;
  plugins?: string[];
  proudlyDisplayPoweredByUppy?: boolean;
  trigger?: string | Element | null;
  locale?: LocaleStrings<typeof locale>;
}

Default Configuration Values

Default values applied when options are not specified.

/**
 * Default configuration values
 */
const defaultOptions = {
  // Modal Options
  inline: false,
  animateOpenClose: true,
  browserBackButtonClose: false,
  closeAfterFinish: false,
  closeModalOnClickOutside: false,
  disablePageScrollWhenModalOpen: true,
  trigger: null,
  
  // Inline Options  
  width: 750,
  height: 550,
  
  // UI Options
  target: 'body',
  theme: 'light',
  autoOpen: null,
  disabled: false,
  disableInformer: false,
  disableLocalFiles: false,
  disableStatusBar: false,
  disableThumbnailGenerator: false,
  
  // File Management
  metaFields: [],
  fileManagerSelectionType: 'files',
  showSelectedFiles: true,
  singleFileFullScreen: true,
  waitForThumbnailsBeforeUpload: false,
  
  // Button Visibility
  hideUploadButton: false,
  hideCancelButton: false,
  hideRetryButton: false,
  hidePauseResumeButton: false,
  hideProgressAfterFinish: false,
  hideProgressDetails: false,
  showLinkToFileUploadResult: false,
  showRemoveButtonAfterComplete: false,
  showNativePhotoCameraButton: false,
  showNativeVideoCameraButton: false,
  
  // Thumbnails
  thumbnailWidth: 280,
  thumbnailType: 'image/jpeg',
  
  // Other
  note: null,
  plugins: [],
  proudlyDisplayPoweredByUppy: true,
  nativeCameraFacingMode: ''
};

Set Dark Mode Capability

Configure dashboard's dark mode capability in Uppy core state.

/**
 * Set dark mode capability
 * Updates Uppy core state to reflect dark mode availability
 * @param isDarkModeOn - Whether dark mode is currently enabled
 */
setDarkModeCapability(isDarkModeOn: boolean): void;

Usage Examples:

// Enable dark mode capability
dashboard.setDarkModeCapability(true);

// Disable dark mode capability  
dashboard.setDarkModeCapability(false);

// Respond to system theme changes
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
mediaQuery.addEventListener('change', (e) => {
  dashboard.setDarkModeCapability(e.matches);
});

setOptions Method

Update dashboard configuration at runtime.

/**
 * Update dashboard options at runtime
 * @param opts - Partial configuration options to update
 */
setOptions(opts: Partial<DashboardOptions<M, B>>): void;

Usage Examples:

// Update theme dynamically
dashboard.setOptions({ theme: "dark" });

// Enable progress details
dashboard.setOptions({ 
  hideProgressDetails: false,
  showLinkToFileUploadResult: true 
});

// Update metadata fields
dashboard.setOptions({
  metaFields: [
    { id: "title", name: "Title", placeholder: "Enter title" },
    { id: "description", name: "Description" }
  ]
});

Install with Tessl CLI