File Upload
Controlled file selection with validation, progress rows, and retry hooks.
File Upload is a standalone package component plus the KuiUploadFile type for controlled state.
import { KuiFileUploadComponent, type KuiUploadFile } from '@kikita-labs/ui';Bind the files model and drive upload transport from your own service.
Drag files here or choose a file
PNG, JPG, or PDF up to 10 MB
<div class="basic-file-upload-example">
<kui-file-upload
acceptLabel="PNG, JPG, or PDF up to 10 MB"
[accept]="['image/png', 'image/jpeg', 'application/pdf']"
[maxSize]="10 * 1024 * 1024"
[maxCount]="3"
[(files)]="files"
(retry)="handleRetry($event)"
/>
</div>The component validates picks, but never uploads bytes by itself.
- Picked files enter the model as pending, or error when client validation fails.
- Consumers update each entry to uploading, success, or error as their transport runs.
- The retry output only reports intent; restart the upload and write new state yourself.
- Use compact variant for dense forms and dropzone when drag-and-drop is useful.
Inputs verified against @kikita-labs/ui v1.6.1 public typings and package docs.
| Name | Type | Default | Description |
|---|---|---|---|
| variant | 'dropzone' | 'compact' | 'dropzone' | Renders the full drag-and-drop zone or a compact attach button. |
| mode | 'single' | 'multiple' | 'multiple' | Controls whether a new selection replaces or appends to the file list. |
| accept | readonly string[] | undefined | Allowed MIME types. Omit it to accept any file type. |
| acceptLabel | string | undefined | Human-readable format and limit hint shown near the picker. |
| maxSize | number | undefined | Maximum file size in bytes. |
| maxCount | number | undefined | Maximum number of files in multiple mode. |
| size | 'sm' | 'md' | 'lg' | 'md' | Controls row height, thumbnail scale, and trigger density. |
| disabled | boolean | false | Stops drag, click, and keyboard file-picking interactions. |
| [(files)] | readonly KuiUploadFile[] | [] | Controlled file list. Consumers own upload status and progress after picking. |
| (retry) | KuiUploadFile | - | Emits when an errored item retry action is activated. |
| KuiUploadFile.status | 'pending' | 'uploading' | 'success' | 'error' | - | Per-file state written by the component initially and then by the consumer. |
Drag-and-drop is optional; keyboard users still activate a native file input.
- Keep the visible acceptLabel specific so the dropzone aria-label is meaningful.
- Use Enter or Space on the dropzone or compact trigger to open the native picker.
- Tab reaches file rows and actions; Delete or Backspace removes a focused file item.
- File Upload is not a Signal Forms control; compose required state around the files model.