AiAttachments
Used to display a set of attachment information. Supports click upload, drag-and-drop upload, and delete; works with AiFileCard for file cards.
When to use
Use when you need to display a set of attachments (e.g. uploading, uploaded, failed) with add/remove support, such as in AI input areas or form attachments.
Basic usage
Bind the attachment list with v-model:items; click to upload and delete. The list is rendered by traversal; for 3+ items each is shown as a card. For delete to work, remove the item in @delete-card (e.g. items.value.splice(index, 1)). Long names are truncated with ellipsis; hover to see full name.
Placeholder
Configure the upload area with placeholder (icon, title, description). Supports object, function, or string shorthand.
Drag and drop
Drop files onto the upload area to upload. Use getDropContainer to set the drop container (default is the component root).
Delete
Each card shows a delete button on hover; delete-card is emitted on click. For delete to take effect, remove the item in the callback (e.g. onDelete(_, index) { items.value.splice(index, 1) }); you can also use the callback for confirmation or server sync.
Multiple states
Items support status: uploading (progress bar), done, error (red border + error text). Use percent, error, description for progress and messages.
Overflow mode
Use overflow to control layout: scrollX, scrollY, or wrap. Demos below use constrained width/height to show the effect.
Upload Function
Basic Usage
The component has built-in upload flow. Click the upload button or drag files to trigger upload. The component will automatically:
- Create file list item (status:
uploading) - Emit
upload-changeevent - Call custom upload function
httpRequest(if provided) - Update status to
doneon success, emitupload-success - Update status to
erroron failure, emitupload-error
Custom Upload
Use httpRequest prop to fully customize upload logic (custom headers, URL, FormData handling, etc.). The function receives { file: File } parameter and must return a Promise.
Monitor Upload Status via Events
API
Props
| Property | Description | Type | Default |
|---|---|---|---|
| items | Attachment list | AttachmentItem[] | [] |
| overflow | Overflow mode | 'wrap' | 'scrollX' | 'scrollY' | 'scrollX' |
| scrollMaxHeight | Max height when overflow is scrollY (e.g. 260px) | string | - |
| hideUpload | Hide upload button | boolean | false |
| disabled | Disabled | boolean | false |
| maxCount | Max file count | number | - |
| limit | File count limit (same as maxCount) | number | - |
| placeholder | Placeholder (object, function, or string) | PlaceholderType | ((mode) => PlaceholderType) | string | - |
| getDropContainer | Return the drop container element; default is component root | () => HTMLElement | - |
| beforeUpload | Pre-upload validation. Return false to cancel | (file: File) => boolean | Promise<boolean> | - |
| httpRequest | Custom upload request function | (options: { file: File }) => Promise<void> | - |
| uploadIconSize | Upload button icon size | string | '24px' |
| dragTarget | Drag target element | string | HTMLElement | - |
| listStyle | List container style | Record<string, string> | {} |
| themeOverrides | Theme override variables | Record<string, unknown> | - |
AttachmentItem Extended Properties
In addition to FileCardListItem properties, attachment items support:
| Property | Description | Type | Default |
|---|---|---|---|
| status | File status | 'uploading' | 'done' | 'error' | 'removed' | - |
| percent | Upload progress (0-100) | number | - |
| response | Response data after successful upload | unknown | - |
| error | Error message | string | - |
Events
| Event | Description | Parameters |
|---|---|---|
| update:items | Fired when list updates | (items: AttachmentItem[]) |
| upload-change | Fired after file select/drop | (file: File, fileList: AttachmentItem[]) |
| upload-success | Fired after successful upload | (response: unknown, file: File, fileList: AttachmentItem[]) |
| upload-error | Fired after upload failure | (error: unknown, file: File, fileList: AttachmentItem[]) |
| upload-drop | Fired on drag drop | (files: File[]) |
| delete-card | Fired when item is deleted | (item: AttachmentItem, index: number) |
| exceed | Fired when exceeding max count | ({ files, maxCount }) |
Slots
| Slot | Description |
|---|---|
| default | Entire component container content |
| file-item | Custom file card item, params: { item: AttachmentItem, index: number } |
| upload-button | Custom upload button, params: { canUpload: boolean } |
| drop-area | Custom drop area content |