syncfusion-angular-inputs

# Implementing Syncfusion Angular Inputs ## Uploader The Syncfusion Angular Uploader (`ejs-uploader`) is a full-featured file upload component that supports asynchronous uploads, chunk uploading of large files, drag-and-drop, clipboard paste, directory upload, file validation, templates, form integration, JWT authentication, and comprehensive event handling. ### Component Overview The Syncfusion Angular Uploader provides: - **Async upload modes:** Auto upload (default) or manual upload with action buttons - **Chunk upload:** Split large files into configurable byte-size chunks with retry logic - **Sequential upload:** Process files one at a time to reduce server traffic - **File sources:** Browse dialog, drag-and-drop, clipboard paste, directory selection - **Validation:** File type (extensions), min/max size, custom count limits, duplicate prevention - **Templates:** Customize the file list item structure; build fully custom upload UIs - **Form support:** HTML form submission, template-driven forms (ngModel), reactive forms (FormGroup) - **Accessibility:** WCAG 2.2, Section 508, keyboard navigation, screen reader support - **Localization:** Customize all static text via L10n ### Documentation & Navigation Guide > ⚠️ **Agentic use note:** This guide links to multiple reference documents. AI agents should read only the sections relevant to the task at hand — do **not** chain through all references automatically. Follow least-privilege reading: fetch only what is needed. #### Getting Started 📄 **Read:** [references/getting-started.md](references/uploader-getting-started.md) - Installation of `@syncfusion/ej2-angular-inputs` ⚠️ **Always verify the package version and integrity before running `npm install` in production pipelines (supply-chain hygiene).** - Package setup, CSS imports, and Angular standalone component usage - Adding the `<ejs-uploader>` component - Configuring async settings (saveUrl, removeUrl) - Handling success and failure events - Adding a custom drop area #### Asynchronous Upload 📄 **Read:** [references/async-upload.md](references/uploader-async-upload.md) - Multiple and single file upload modes (`multiple` property) - Save action configuration and server-side handling - Remove action and `postRawFile` usage - Auto upload vs manual upload (`autoUpload` property) - Sequential upload (`sequentialUpload`) - Preloaded files (`files` property) - Adding custom HTTP headers to upload requests #### Chunk Upload 📄 **Read:** [references/chunk-upload.md](references/uploader-chunk-upload.md) - Enabling chunk upload via `asyncSettings.chunkSize` - Pause, resume, and cancel chunk uploads - Retry configuration (`retryCount`, `retryAfterDelay`) - `chunkSuccess` and `chunkFailure` events - Server-side chunk assembly implementation #### File Validation 📄 **Read:** [references/validation.md](references/uploader-validation.md) - Restricting file types with `allowedExtensions` - Min/max file size constraints (`minFileSize`, `maxFileSize`) - Limiting upload count via the `selected` event - Preventing duplicate file uploads - MIME type validation before upload - Image/* validation on drag-and-drop #### File Sources 📄 **Read:** [references/file-sources.md](references/uploader-file-sources.md) - Paste images from clipboard - Directory (folder) upload with `directoryUpload` - Drag-and-drop with built-in and custom drop areas - Custom drop area styling (`.e-upload-drag-hover`) - Triggering file browse from an external button #### Templates & Custom UI 📄 **Read:** [references/templates-and-custom-ui.md](references/uploader-templates-and-custom-ui.md) - File list template with the `template` property - Building a completely custom upload UI (hiding default list with `showFileList`) - Customizing action buttons with HTML elements (`buttons` property) - Customizing the progress bar appearance - Preview images before uploading - Resize images before uploading to server #### Form Integration 📄 **Read:** [references/form-integration.md](references/uploader-form-integration.md) - Using Uploader inside HTML forms (synchronous submission) - Template-driven forms with `ngModel` - Reactive forms with `FormGroup` - Required field validation (`required` attribute) - Reset behavior with form reset #### Styling & Appearance 📄 **Read:** [references/styling-and-appearance.md](references/uploader-styling-and-appearance.md) - Customizing the uploader wrapper dimensions - Styling the browse button - Customizing the drop area text - Customizing the file list container - Hiding the default drop area - CSS class reference for key Uploader elements #### Accessibility & Localization 📄 **Read:** [references/accessibility-and-localization.md](references/uploader-accessibility-and-localization.md) - WCAG 2.2, Section 508, keyboard shortcuts - Screen reader and RTL support - Localizing all static labels and messages with L10n #### Advanced How-To Patterns 📄 **Read:** [references/advanced-patterns.md](references/uploader-advanced-patterns.md) - Upload files programmatically with the `upload()` method - Invisible (background) upload - Adding additional form data with `customFormData` - JWT authentication for upload/remove requests - Show confirmation dialog before removing files - Get total size of selected files - Sort selected files in the file list - Open and edit uploaded files from the server - Convert uploaded images to binary format #### API Reference 📄 **Read:** [references/api.md](references/uploader-api.md) - Complete properties, methods, and events reference - AsyncSettingsModel, ButtonsPropsModel, FilesPropModel - All event argument types and their fields ### Quick Start Example Minimal file uploader with async upload (Angular 21+ standalone): ```typescript import { Component } from '@angular/core'; import { UploaderModule } from '@syncfusion/ej2-angular-inputs'; @Component({ imports: [UploaderModule], standalone: true, selector: 'app-root', template: ` <ejs-uploader [asyncSettings]="asyncSettings" [autoUpload]="false" (success)="onSuccess($event)" (failure)="onFailure($event)"> </ejs-uploader> ` }) export class AppComponent { public asyncSettings = { saveUrl: 'https://your-api/upload/save', // Replace with your actual endpoint removeUrl: 'https://your-api/upload/remove' // Replace with your actual endpoint }; onSuccess(args: any): void { console.log('Upload operation:', args.operation, 'File:', args.file.name); } onFailure(args: any): void { console.error('Upload failed:', args.file.name); } } ``` **CSS Theme Setup** (`styles.css`): ```css @import 'node_modules/@syncfusion/ej2-base/styles/material3.css'; @import 'node_modules/@syncfusion/ej2-buttons/styles/material3.css'; @import 'node_modules/@syncfusion/ej2-inputs/styles/material3.css'; @import 'node_modules/@syncfusion/ej2-popups/styles/material3.css'; @import 'node_modules/@syncfusion/ej2-angular-inputs/styles/material3.css'; ``` ### Common Patterns #### Pattern 1: Auto Upload with Drag-and-Drop ```typescript // Automatically uploads dropped or browsed files <ejs-uploader [asyncSettings]="asyncSettings" [dropArea]="dropElement" [multiple]="true" (success)="onSuccess($event)"> </ejs-uploader> ``` #### Pattern 2: Chunk Upload for Large Files ```typescript <ejs-uploader [asyncSettings]="chunkSettings" (chunkSuccess)="onChunkSuccess($event)" (chunkFailure)="onChunkFailure($event)"> </ejs-uploader> // In component: chunkSettings = { saveUrl: 'https://your-api/upload/save', // Replace with your actual endpoint removeUrl: 'https://your-api/upload/remove', // Replace with your actual endpoint chunkSize: 500000 // 500 KB chunks }; ``` #### Pattern 3: Validated Upload (Type + Size) ```typescript <ejs-uploader [asyncSettings]="asyncSettings" allowedExtensions=".jpg,.png,.pdf" [minFileSize]="1024" [maxFileSize]="5000000"> </ejs-uploader> ``` #### Pattern 4: Preloaded Files ```typescript <ejs-uploader [asyncSettings]="asyncSettings" [files]="preloadedFiles"> </ejs-uploader> // In component: preloadedFiles = [ { name: 'report', size: 200000, type: '.pdf' }, { name: 'photo', size: 500000, type: '.jpg' } ]; ``` ### Pattern 5: JWT-Authenticated Upload ```typescript <ejs-uploader [asyncSettings]="asyncSettings" (uploading)="addAuthHeader($event)" (removing)="addAuthHeader($event)"> </ejs-uploader> // ⚠️ Never hardcode tokens — always retrieve from a secure auth service (e.g., Angular AuthService or OAuth library). // ⚠️ Always transmit tokens over HTTPS only. Never pass tokens as URL query parameters. addAuthHeader(args: any): void { args.currentRequest.setRequestHeader('Authorization', `Bearer ${this.token}`); } ``` ### Key Properties | Property | Type | Default | Purpose | |----------|------|---------|---------| | `[asyncSettings]` | AsyncSettingsModel | `{saveUrl:'',removeUrl:''}` | Server save/remove URLs and chunk config | | `[autoUpload]` | boolean | `true` | Upload immediately on file selection | | `[multiple]` | boolean | `true` | Allow selecting multiple files | | `[allowedExtensions]` | string | `''` | Comma-separated allowed extensions (e.g., `.jpg,.png`) | | `[minFileSize]` | number | `0` | Minimum file size in bytes | | `[maxFileSize]` | number | `30000000` | Maximum file size in bytes (~28.6 MB) | | `[files]` | FilesPropModel[] | `[]` | Preloaded files from server | | `[dropArea]` | string \| HTMLElement | `null` | Custom drop target element or selector | | `[directoryUpload]` | boolean | `false` | Enable folder/directory upload | | `[sequentialUpload]` | boolean | `false` | Upload files one at a time | | `[showFileList]` | boolean | `true` | Show/hide default file list | | `[template]` | any | `null` | Custom file list item template | | `[buttons]` | ButtonsPropsModel | `{browse,clear,upload}` | Customize button text/HTML | | `[enabled]` | boolean | `true` | Enable or disable the component | | `[cssClass]` | string | `''` | Additional CSS classes on root element | | `[enableRtl]` | boolean | `false` | Right-to-left rendering | | `[enableHtmlSanitizer]` | boolean | `true` | Prevent XSS in filenames | | `[dropEffect]` | DropEffect | `'Default'` | Drag effect: Copy, Move, Link, None | ### Key Events | Event | When it Fires | Key Args | |-------|---------------|----------| | `(selected)` | Files selected or dropped | `filesData`, `cancel`, `modifiedFilesData` | | `(uploading)` | Before each file upload starts | `fileData`, `currentRequest`, `customFormData`, `cancel` | | `(success)` | Upload or remove succeeds | `file`, `operation` (`upload`\|`remove`), `event` | | `(failure)` | Upload or remove fails | `file`, `operation`, `event` | | `(progress)` | Upload progress | `file`, `event` (loaded, total) | | `(removing)` | Before file remove request | `filesData`, `postRawFile`, `currentRequest` | | `(beforeRemove)` | Before remove confirmation | `filesData`, `cancel` | | `(beforeUpload)` | Before upload process | `fileData`, `customFormData` | | `(change)` | File list changes | `file` | | `(clearing)` | Before clear all action | `cancel` | | `(chunkSuccess)` | Each chunk uploads OK | `chunkIndex`, `totalChunk`, `chunkSize`, `file` | | `(chunkFailure)` | Each chunk fails | `chunkIndex`, `totalChunk`, `chunkSize`, `file`, `cancel` | | `(chunkUploading)` | Before each chunk upload | `fileData`, `currentRequest`, `customFormData` | | `(pausing)` | Chunk upload paused | `file`, `chunkIndex` | | `(resuming)` | Chunk upload resumed | `file`, `chunkIndex` | | `(canceling)` | Upload canceled | `file` | | `(fileListRendering)` | Before each file item renders | `element`, `fileInfo` | | `(actionComplete)` | All files processed | `fileData` | | `(created)` | Component initialized | — | ### Key Methods | Method | Purpose | |--------|---------| | `upload(files?, custom?)` | Programmatically start upload for selected or specific files |