or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdfile-editor.mdfile-management.mdindex.mdmodal-management.mdpanel-management.mdplugin-integration.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@uppy/dashboard@5.0.x

To install, run

npx @tessl/cli install tessl/npm-uppy--dashboard@5.0.0

index.mddocs/

@uppy/dashboard

@uppy/dashboard is a universal UI plugin for Uppy that provides a comprehensive dashboard interface for file upload management. It offers drag-and-drop functionality, file previews, metadata editing, progress tracking, and seamless integration with remote storage providers through optional plugins.

Package Information

  • Package Name: @uppy/dashboard
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @uppy/dashboard

Core Imports

import Dashboard from "@uppy/dashboard";
import type { DashboardOptions } from "@uppy/dashboard";

For CommonJS:

const Dashboard = require("@uppy/dashboard");

Basic Usage

import Uppy from "@uppy/core";
import Dashboard from "@uppy/dashboard";

// Create Uppy instance
const uppy = new Uppy();

// Add Dashboard plugin
uppy.use(Dashboard, {
  target: "#uppy-dashboard",
  inline: true,
  width: 750,
  height: 550,
  showProgressDetails: true,
  hideUploadButton: false,
  theme: "light"
});

Architecture

@uppy/dashboard is built around several key components:

  • Dashboard Class: Main plugin extending UIPlugin from @uppy/core
  • Modal/Inline Modes: Supports both overlay modal and embedded inline display
  • Plugin Integration: Automatic discovery and mounting of acquirer, editor, and progress indicator plugins
  • State Management: Comprehensive state tracking for UI elements, files, and user interactions
  • Event System: Rich event emission for customization and integration hooks
  • Theme System: Support for light, dark, and auto themes with system preference detection

Capabilities

Modal Management

Control dashboard visibility and interaction modes for overlay-style file selection interfaces.

interface Dashboard {
  /** Open the dashboard modal interface */
  openModal(): Promise<void>;
  /** Close the dashboard modal with optional manual close flag */
  closeModal(opts?: { manualClose: boolean }): void | Promise<void>;
  /** Check if modal is currently open */
  isModalOpen(): boolean;
}

Modal Management

Panel Management

Manage visibility and state of plugin panels within the dashboard interface.

interface Dashboard {
  /** Show specific plugin panel by ID */
  showPanel(id: string): void;
  /** Hide all currently open panels */
  hideAllPanels(): void;
}

Panel Management

File Management

Handle file selection, metadata editing, and file operations within the dashboard.

interface Dashboard {
  /** Add files to the uploader */
  addFiles(files: File[]): void;
  /** Save file metadata */
  saveFileCard(meta: Meta, fileID: string): void;
}

File Management

File Editor Integration

Integrate with file editor plugins for image editing and metadata management.

interface Dashboard {
  /** Open file editor for specific file */
  openFileEditor(file: UppyFile): void;
  /** Close file editor panel */
  closeFileEditor(): void;
  /** Save file editor changes */
  saveFileEditor(): void;
}

File Editor Integration

Plugin Target Management

Register and manage plugins that integrate with the dashboard interface.

interface Dashboard {
  /** Register plugin as dashboard target */
  addTarget(plugin: UnknownPlugin): HTMLElement | null;
  /** Unregister plugin target */
  removeTarget(plugin: UnknownPlugin): void;
}

Plugin Integration

Configuration Management

Configure dashboard appearance, behavior, and feature availability.

interface Dashboard {
  /** Update dashboard options */
  setOptions(opts: Partial<DashboardOptions>): void;
  /** Set dark mode capability */
  setDarkModeCapability(isDarkModeOn: boolean): void;
}

type DashboardOptions<M extends Meta, B extends Body> = 
  DashboardMiscOptions<M, B> & 
  (DashboardModalOptions | DashboardInlineOptions);

Configuration

Dashboard Class

/** Main Dashboard class extending UIPlugin */
class Dashboard<M extends Meta, B extends Body> extends UIPlugin {
  /** Package version string */
  static VERSION: string;
  
  /** Check if file can be edited with available editor plugins */
  canEditFile(file: UppyFile<M, B>): boolean;
}

Global Types

/** Dashboard state interface */
interface DashboardState<M extends Meta, B extends Body> {
  targets: Target[];
  activePickerPanel: Target | undefined;
  showAddFilesPanel: boolean;
  activeOverlayType: string | null;
  fileCardFor: string | null;
  showFileEditor: boolean;
  metaFields?: MetaField[] | ((file: UppyFile<M, B>) => MetaField[]);
  isHidden: boolean;
  isClosing: boolean;
  containerWidth: number;
  containerHeight: number;
  areInsidesReadyToBeVisible: boolean;
  isDraggingOver: boolean;
  [key: string]: unknown;
}

/** Plugin target interface */
interface Target {
  id: string;
  name: string;
  type: string;
}

/** Target with render capabilities */
interface TargetWithRender extends Target {
  icon: () => ComponentChild;
  render: () => ComponentChild;
}

/** Metadata field configuration */
interface MetaField {
  id: string;
  name: string;
  placeholder?: string;
  render?: (field: FieldRenderOptions, h: PreactRender) => VNode<any>;
}

/** Field render options */
interface FieldRenderOptions {
  value: string;
  onChange: (newVal: string) => void;
  fieldCSSClasses: { text: string };
  required: boolean;
  form: string;
}

CSS Integration

@uppy/dashboard includes comprehensive CSS styling:

// ES6 imports
import "@uppy/dashboard/dist/style.css";
// or minified version
import "@uppy/dashboard/dist/style.min.css";

Alternative import paths (from package.json exports):

// Using package.json exports
import "@uppy/dashboard/css/style.css";
import "@uppy/dashboard/css/style.min.css";

HTML link tags:

<!-- CDN -->
<link rel="stylesheet" href="https://releases.transloadit.com/uppy/v5.0.1/uppy.min.css">

<!-- Local file -->
<link rel="stylesheet" href="node_modules/@uppy/dashboard/dist/style.min.css">

CSS-in-JS frameworks:

// Next.js
import "@uppy/dashboard/dist/style.css";

// Webpack
require("@uppy/dashboard/dist/style.css");