---
metaTitle: Uploader component | AwesCode UI
meta:
  - name: description
    content: The <AwUploader /> component is used to render Uploader - UI Vue component for AwesCode UI.
title: Uploader
---

# AwUploader

**Category:** Organism | **Import:** Dynamic

The `AwUploader` component is a file upload component with drag-and-drop support, progress tracking, and file validation. It handles file uploads via FormData and provides upload lifecycle events.

## Overview

`AwUploader` provides a file upload solution with:
- Drag and drop file upload
- Click to select files
- File format validation
- File size validation
- Upload progress tracking
- Multiple file support
- Cancel upload functionality
- Error handling

## Usage

### Basic Example

```markup
<AwUploader
    url="/api/upload"
    @start="handleStart"
    @finish="handleFinish"
    @error="handleError"
/>
```

### Single File

```markup
<AwUploader
    url="/api/upload"
    :max="5"
    format="['image/jpeg', 'image/png']"
/>
```

### Multiple Files

```markup
<AwUploader
    url="/api/upload"
    multiple
    :max="10"
    format="['image/*']"
/>
```

### Custom Format

```markup
<AwUploader
    url="/api/upload"
    :format="['.pdf', '.doc', '.docx']"
    :max="20"
/>
```

### Custom Label

```markup
<AwUploader url="/api/upload">
    <template #label="{ isDragging }">
        <div :class="{ 'opacity-50': isDragging }">
            Custom upload area
        </div>
    </template>
</AwUploader>
```

### Hide Progress

```markup
<AwUploader
    url="/api/upload"
    hide-progress
/>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| url | API endpoint URL for file upload | `String` | `true` | - |
| name | Form field name for file input | `String` | `false` | `'file'` |
| format | Allowed file formats (MIME types or extensions) | `Array` | `false` | `[]` |
| max | Maximum file size in MB | `Number` | `false` | `2` |
| multiple | Allow multiple file selection | `Boolean` | `false` | `false` |
| hideProgress | Hide progress bar | `Boolean` | `false` | `false` |

**Format Examples:**
```javascript
['image/jpeg', 'image/png']  // MIME types
['.pdf', '.doc', '.docx']     // File extensions
['image/*']                    // Wildcard MIME types
```

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| label | Custom upload area content | `{ isDragging }` | Default icon and text |
| drag-over | Content shown when dragging over | `{ isDragging }` | Default file icon |

### Events

| Name | Payload | Description |
|------|---------|-------------|
| start | `{ id, file, loading, progress, cancel }` | Emitted when upload starts |
| progress | `{ id, file, loading, progress, cancel }` | Emitted during upload progress |
| finish | `{ id, response }` | Emitted when upload completes successfully |
| error | `{ id, response }` | Emitted when upload fails |

**Event Payload:**
```javascript
{
  id: 1,                    // Unique file ID
  file: File,               // File object
  loading: true,            // Upload in progress
  progress: 50,            // Upload progress (0-100)
  cancel: Function,        // Cancel upload function
  response: Object         // Axios response (finish/error)
}
```

### Mixins

- `errorMixin` - Provides error handling functionality

## Related Components

- `AwUploaderFiles` - Component for displaying uploaded files list
- `AwButton` - Button component (used in examples)
- `AwProgress` - Progress component (used internally)

## Notes

- **Import Method:** Dynamic - Component is loaded on-demand as an organism
- Files are uploaded using FormData via Axios
- Drag and drop works across the entire document (global listeners)
- File validation happens before upload starts
- Upload can be cancelled using `cancel()` function from event payload
- Progress is tracked per file (for multiple uploads)
- Component uses Axios cancel tokens for cancellation
- Error messages are displayed via tooltip
- Format validation uses file MIME type or extension
- Size validation compares file size to `max` prop (in MB)
- Component registers global drag listeners (one per page)
- Dropzone overlay appears when dragging files over component