0
# @uppy/file-input
1

2
@uppy/file-input is a minimalist file input plugin for the Uppy file uploading ecosystem. It renders a simple button that triggers the browser's native file selection dialog when clicked, making it the most basic UI plugin available in Uppy's plugin architecture.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import FileInput from "@uppy/file-input";
15
import type { FileInputOptions } from "@uppy/file-input";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const FileInput = require("@uppy/file-input");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import Uppy from "@uppy/core";
28
import FileInput from "@uppy/file-input";
29

30
// Create Uppy instance
31
const uppy = new Uppy();
32

33
// Add FileInput plugin
34
uppy.use(FileInput, {
35
  target: '#upload-form',
36
  pretty: true,
37
  inputName: 'files[]'
38
});
39

40
// Listen for files
41
uppy.on('files-added', (files) => {
42
  console.log('Files selected:', files);
43
});
44
```
45

46
## Architecture
47

48
@uppy/file-input follows Uppy's plugin architecture pattern:
49

50
- **Plugin Base**: Extends `UIPlugin` from `@uppy/core` for DOM rendering capabilities
51
- **Lifecycle Management**: Implements `install()` and `uninstall()` methods for proper cleanup
52
- **Event-Driven**: Uses Uppy's event system to communicate file selection to the core
53
- **UI Rendering**: Uses Preact for efficient DOM updates and component rendering
54
- **Localization**: Supports i18n through Uppy's translation system
55

56
The plugin creates either a native file input or a styled button that triggers file selection, then processes selected files through Uppy's standard file handling pipeline.
57

58
## Capabilities
59

60
### FileInput Plugin Class
61

62
The main plugin class that integrates with Uppy Core to provide file input functionality.
63

64
```typescript { .api }
65
import type { Uppy, Meta, Body, UIPlugin } from '@uppy/core';
66
import type { ComponentChild } from 'preact';
67

68
export default class FileInput<M extends Meta, B extends Body> extends UIPlugin<
69
  FileInputOptions,
70
  M,
71
  B
72
> {
73
  static VERSION: string;
74
  input: HTMLFileInputElement | null;
75
  
76
  constructor(uppy: Uppy<M, B>, opts?: FileInputOptions);
77
  
78
  addFiles(files: File[]): void;
79
  render(): ComponentChild;
80
  install(): void;
81
  uninstall(): void;
82
}
83
```
84

85
**Usage:**
86

87
```typescript
88
import Uppy from "@uppy/core";
89
import FileInput from "@uppy/file-input";
90

91
const uppy = new Uppy();
92
const fileInput = new FileInput(uppy, {
93
  target: '#my-form',
94
  pretty: true,
95
  inputName: 'uploads[]'
96
});
97

98
uppy.use(fileInput);
99
```
100

101
### Add Files Method
102

103
Programmatically adds files to the Uppy instance.
104

105
```typescript { .api }
106
/**
107
 * Adds files to the Uppy instance
108
 * @param files - Array of File objects to add
109
 */
110
addFiles(files: File[]): void;
111
```
112

113
**Usage:**
114

115
```typescript
116
// Manually add files (typically used internally)
117
const files = [new File(['content'], 'example.txt', { type: 'text/plain' })];
118
fileInput.addFiles(files);
119
```
120

121
### Plugin Installation
122

123
Installs the plugin to the specified target element.
124

125
```typescript { .api }
126
/**
127
 * Installs the plugin and mounts it to the target element
128
 */
129
install(): void;
130

131
/**
132
 * Removes the plugin from the DOM
133
 */
134
uninstall(): void;
135
```
136

137
## Configuration Options
138

139
Configuration interface for customizing the FileInput plugin behavior.
140

141
```typescript { .api }
142
import type { UIPluginOptions } from '@uppy/core';
143
import type { LocaleStrings } from '@uppy/utils/lib/Translator';
144

145
export interface FileInputOptions extends UIPluginOptions {
146
  /** Whether to show a styled button instead of native input (default: true) */
147
  pretty?: boolean;
148
  /** Name attribute for the file input element (default: 'files[]') */
149
  inputName?: string;
150
  /** Custom localization strings */
151
  locale?: LocaleStrings<FileInputLocale>;
152
}
153

154
interface FileInputLocale {
155
  strings: {
156
    chooseFiles: string;
157
  };
158
}
159
```
160

161
**Usage:**
162

163
```typescript
164
uppy.use(FileInput, {
165
  target: '#upload-area',
166
  pretty: true,           // Show styled button
167
  inputName: 'documents[]', // Form input name
168
  locale: {
169
    strings: {
170
      chooseFiles: 'Select Files'  // Custom button text
171
    }
172
  }
173
});
174
```
175

176
## Localization
177

178
Default locale configuration for internationalization support.
179

180
```typescript { .api }
181
// Default locale configuration
182
interface FileInputLocale {
183
  strings: {
184
    chooseFiles: string;
185
  };
186
}
187
```
188

189
The default English locale provides:
190

191
```typescript
192
{
193
  strings: {
194
    chooseFiles: 'Choose files'
195
  }
196
}
197
```
198

199
**Custom Localization:**
200

201
```typescript
202
uppy.use(FileInput, {
203
  target: '#upload',
204
  locale: {
205
    strings: {
206
      chooseFiles: 'Dateien auswählen'  // German
207
    }
208
  }
209
});
210
```
211

212
## Types
213

214
Core types used throughout the FileInput plugin.
215

216
```typescript { .api }
217
// Core types from @uppy/core
218
export interface Meta {
219
  [key: string]: unknown;
220
}
221

222
export interface Body {
223
  [key: string]: unknown;
224
}
225

226
export interface Uppy<M extends Meta = Meta, B extends Body = Body> {
227
  // Core Uppy instance interface
228
  addFiles(files: Array<{ source: string; name: string; type: string; data: File }>): void;
229
  log(message: unknown): void;
230
  // ... other Uppy methods
231
}
232

233
export interface UIPluginOptions {
234
  id?: string;
235
  target?: string | Element;
236
}
237

238
// Internal types
239
interface HTMLFileInputElement extends HTMLInputElement {
240
  files: FileList;
241
}
242

243
type DefinePluginOpts<T, K extends keyof T> = T & Required<Pick<T, K>>;
244
```
245

246
## Browser Compatibility
247

248
@uppy/file-input works in all modern browsers that support:
249
- HTML5 File API
250
- ES6+ features (when using TypeScript/ES modules)
251
- Preact rendering (handled internally)
252

253
The plugin automatically handles:
254
- Multiple file selection based on Uppy restrictions
255
- File type filtering via the `accept` attribute
256
- Input clearing after selection to enable re-selection of same files