0
# Status Bar
1

2
Status Bar is a TypeScript-based UI plugin for the Uppy file uploader that provides a comprehensive progress bar with upload controls. It displays real-time upload progress, transfer speeds, ETAs, pre- and post-processing information, and allows users to control (pause/resume/cancel) uploads.
3

4
## Package Information
5

6
- **Package Name**: @uppy/status-bar
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @uppy/status-bar`
10

11
## Core Imports
12

13
```typescript
14
import StatusBar from "@uppy/status-bar";
15
import type { StatusBarOptions } from "@uppy/status-bar";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const StatusBar = require("@uppy/status-bar");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import Uppy from "@uppy/core";
28
import StatusBar from "@uppy/status-bar";
29

30
const uppy = new Uppy();
31
uppy.use(StatusBar, {
32
  target: "#status-bar",
33
  showProgressDetails: true,
34
  hideUploadButton: false,
35
  hideAfterFinish: true,
36
});
37

38
// The status bar will automatically display upload progress
39
// and provide controls for pause/resume/cancel operations
40
```
41

42
## Architecture
43

44
Status Bar is built around several key components:
45

46
- **StatusBar Plugin**: Main plugin class extending UIPlugin that manages upload state and renders UI
47
- **StatusBarUI Component**: Preact component that renders the visual interface
48
- **State Management**: Tracks upload progress, speed calculations, and ETA estimations  
49
- **UI Components**: Individual button and progress bar components for different states
50
- **Localization**: Full internationalization support with default English strings
51

52
## Capabilities
53

54
### Status Bar Plugin
55

56
Main plugin class that provides upload progress visualization and control functionality.
57

58
```typescript { .api }
59
/**
60
 * StatusBar plugin for Uppy that renders upload progress with controls
61
 */
62
export default class StatusBar<M extends Meta, B extends Body> extends UIPlugin<
63
  DefinePluginOpts<StatusBarOptions, keyof typeof defaultOptions>,
64
  M,
65
  B
66
> {
67
  /** Plugin version string matching package version */
68
  static VERSION: string;
69
  
70
  /**
71
   * Creates a new StatusBar plugin instance
72
   * @param uppy - Uppy instance to attach to
73
   * @param opts - Configuration options for the status bar
74
   */
75
  constructor(uppy: Uppy<M, B>, opts?: StatusBarOptions);
76
  
77
  /**
78
   * Initiates the upload process
79
   * @returns Promise that resolves when upload starts, or undefined if upload fails
80
   */
81
  startUpload(): ReturnType<Uppy<M, B>['upload']>;
82
  
83
  /**
84
   * Renders the status bar UI component
85
   * @param state - Current Uppy state containing files, progress, and capabilities
86
   * @returns Preact component for rendering the status bar interface
87
   */
88
  render(state: State<M, B>): ComponentChild;
89
  
90
  /**
91
   * Called when plugin is mounted to DOM - sets text direction if needed
92
   */
93
  onMount(): void;
94
  
95
  /**
96
   * Installs the plugin and sets up event listeners for upload events
97
   */
98
  install(): void;
99
  
100
  /**
101
   * Uninstalls the plugin and cleans up resources including event listeners
102
   */
103
  uninstall(): void;
104
}
105
```
106

107
### Configuration Options
108

109
Configuration interface for customizing status bar behavior and appearance.
110

111
```typescript { .api }
112
/**
113
 * Configuration options for StatusBar plugin
114
 */
115
interface StatusBarOptions extends UIPluginOptions {
116
  /** Show detailed progress information including file counts and data amounts */
117
  showProgressDetails?: boolean;
118
  /** Hide the upload button */
119
  hideUploadButton?: boolean;
120
  /** Hide status bar after upload completion */
121
  hideAfterFinish?: boolean;
122
  /** Hide retry button */
123
  hideRetryButton?: boolean;
124
  /** Hide pause/resume button */
125
  hidePauseResumeButton?: boolean;
126
  /** Hide cancel button */
127
  hideCancelButton?: boolean;
128
  /** Custom handler for done button click */
129
  doneButtonHandler?: (() => void) | null;
130
  /** Localization strings for UI text */
131
  locale?: LocaleStrings<typeof StatusBarLocale>;
132
}
133

134
/**
135
 * Base UI plugin options inherited by StatusBarOptions
136
 */
137
interface UIPluginOptions {
138
  /** Target element or selector for mounting the plugin */
139
  target?: string | Element;
140
  /** Unique identifier for the plugin instance */
141
  id?: string;
142
}
143

144
/**
145
 * Default configuration values for StatusBar plugin
146
 */
147
const defaultOptions = {
148
  hideUploadButton: false,
149
  hideRetryButton: false,
150
  hidePauseResumeButton: false,
151
  hideCancelButton: false,
152
  showProgressDetails: false,
153
  hideAfterFinish: true,
154
  doneButtonHandler: null,
155
};
156

157
/**
158
 * Locale strings interface for StatusBar
159
 */
160
interface StatusBarLocale {
161
  strings: {
162
    uploading: string;
163
    complete: string;
164
    uploadFailed: string;
165
    paused: string;
166
    retry: string;
167
    cancel: string;
168
    pause: string;
169
    resume: string;
170
    done: string;
171
    filesUploadedOfTotal: Record<number, string>;
172
    dataUploadedOfTotal: string;
173
    dataUploadedOfUnknown: string;
174
    xTimeLeft: string;
175
    uploadXFiles: Record<number, string>;
176
    uploadXNewFiles: Record<number, string>;
177
    upload: string;
178
    retryUpload: string;
179
    xMoreFilesAdded: Record<number, string>;
180
    showErrorDetails: string;
181
  };
182
}
183
```
184

185

186
## CSS Styling
187

188
The package includes pre-built CSS stylesheets for styling the status bar:
189

190
```typescript
191
// Import minified CSS (recommended for production)
192
import "@uppy/status-bar/css/style.min.css";
193

194
// Or import regular CSS (for development/customization)
195
import "@uppy/status-bar/css/style.css";
196
```
197

198
The status bar uses CSS classes with the `uppy-` prefix for styling. Key classes include:
199
- `.uppy-StatusBar-content` - Main status bar container
200
- `.uppy-StatusBar-progress` - Progress bar element
201
- `.uppy-StatusBar-actionBtn` - Action button styling
202
- `.uppy-StatusBar-details` - Progress details text
203

204
## Error Handling
205

206
The status bar automatically handles and displays upload errors:
207

208
- **Network errors**: Displays retry option
209
- **File validation errors**: Shows error details
210
- **Server errors**: Provides retry functionality
211
- **Cancellation**: Gracefully handles user cancellation
212

213
## Types
214

215
Core types used throughout the status bar API:
216

217
```typescript { .api }
218
// Core types (re-exported from @uppy/core)
219
type Meta = Record<string, unknown>;
220
type Body = Record<string, unknown>;
221

222
// From preact
223
type ComponentChild = VNode<any> | object | string | number | bigint | boolean | null | undefined;
224

225
interface UppyFile<M extends Meta, B extends Body> {
226
  id: string;
227
  name?: string;
228
  type: string;
229
  data: File | Blob;
230
  meta: InternalMetadata & M;
231
  size: number | null;
232
  isRemote: boolean;
233
  isGhost: boolean;
234
  progress: FileProgress;
235
  error?: string | null;
236
  extension: string;
237
  isPaused?: boolean;
238
  isRestored?: boolean;
239
  preview?: string;
240
  uploadURL?: string;
241
  response?: {
242
    body?: B;
243
    status: number;
244
    bytesUploaded?: number;
245
    uploadURL?: string;
246
  };
247
}
248

249
interface FileProgress {
250
  uploadStarted: boolean;
251
  uploadComplete: boolean;
252
  percentage: number;
253
  bytesUploaded: number;
254
  bytesTotal: number | null;
255
  preprocess?: FileProcessingInfo;
256
  postprocess?: FileProcessingInfo;
257
}
258

259
interface FileProcessingInfo {
260
  mode: string;
261
  fileIDs: string[];
262
}
263

264
interface InternalMetadata {
265
  name: string;
266
  type?: string;
267
}
268

269
interface State<M extends Meta, B extends Body> {
270
  meta: M;
271
  capabilities: {
272
    uploadProgress: boolean;
273
    individualCancellation: boolean;
274
    resumableUploads: boolean;
275
    isMobileDevice?: boolean;
276
    darkMode?: boolean;
277
  };
278
  files: Record<string, UppyFile<M, B>>;
279
  allowNewUpload: boolean;
280
  totalProgress: number;
281
  error: string | null;
282
  recoveredState: any;
283
  currentUploads: Record<string, any>;
284
  info: Array<{
285
    isHidden?: boolean;
286
    type: string;
287
    message: string;
288
    details?: string | Record<string, string> | null;
289
  }>;
290
  plugins: Record<string, any>;
291
  companion?: Record<string, string>;
292
}
293

294
// Plugin configuration types
295
interface DefinePluginOpts<Opts, AlwaysDefinedKeys extends keyof Opts> {
296
  [K in keyof Opts]: K extends AlwaysDefinedKeys ? Opts[K] : Opts[K];
297
}
298

299
// From @uppy/utils
300
interface I18n {
301
  (key: string, options?: Record<string, any>): string;
302
}
303

304
interface LocaleStrings<T> {
305
  strings: Partial<T>;
306
}
307
```