File Upload

The file upload primitive allows you to trigger a file upload from any element, giving you the more control over the appearance and behavior compared to the native file input.

Import

Import the FileUpload primitives from ng-primitives/file-upload.

import { NgpFileUpload } from 'ng-primitives/file-upload';

Usage

Assemble the file-upload directives in your template.

<button
  ngpFileUpload
  (ngpFileUploadSelected)="onFilesSelected($event)"
  (ngpFileUploadCanceled)="onCancel()"
></button>

Reusable Component

Create a file upload component that uses the NgpFileUpload directive.

Schematics

Generate a reusable file upload component using the Angular CLI.

ng g ng-primitives:primitive file-upload

Options

• path: The path at which to create the component file.
• prefix: The prefix to apply to the generated component selector.
• component-suffix: The suffix to apply to the generated component class name.
• file-suffix: The suffix to apply to the generated component file name. Defaults to component.
• styles: How component styles should be generated. css (default) includes the full example styles; unstyled omits them entirely so you can style the component yourself.
• example-styles (deprecated): still supported for compatibility - true maps to styles: css, false maps to styles: unstyled.

Examples

File Dropzone

The file dropzone primitive allows you to create a dropzone for files. This functionality is built into the file upload primitive, but can also be used separately if you don't want to show the file upload dialog on click.

Validating Files

Limit what can be selected with fileTypes, maxFileSize (in bytes) and multiple. Every source is validated the same way, including files chosen in the dialog, where accept is only a hint the user can bypass.

Valid files are emitted through selected. Every file that fails is emitted through rejectedFiles along with the reasons it failed ('type', 'size' or 'count' for files beyond the first when multiple is off), even when other files were accepted. rejected only fires when no file was accepted.

<button
  ngpFileUpload
  ngpFileUploadFileTypes="image/*,.pdf"
  ngpFileUploadMaxFileSize="5242880"
  (ngpFileUploadSelected)="upload($event)"
  (ngpFileUploadRejectedFiles)="showErrors($event)"
>
  Upload
</button>

Pasting Files

Pasting is opt-in. Set paste to 'host' (or add the bare attribute) to accept files pasted while the element is focused, or to 'document' to accept files pasted anywhere on the page. Pasted files go through the same validation as dropped files, and pastes that contain no files, or that land in a text field, are left alone.

Document mode pairs well with a dialog: the dropzone, and its paste listener, only exist while the dialog is open, so users can paste without focusing anything first.

In host mode an element that is not already focusable gets tabindex="0", as a paste only reaches the focused element. Document-mode instances ignore a paste aimed at another focused file upload or dropzone, whatever that one's paste setting, unless it sits inside them (such as a browse button in the dropzone), in which case the document-mode instance still handles it. With several document-mode instances and none focused, the order they receive a paste in is not guaranteed, so keep to one per page.

API Reference

The following directives are available to import from the ng-primitives/file-upload package:

NgpFileUpload

NgpFileDropzone

Global Configuration

You can configure the default options for all file uploads and file dropzones in your application by using the provideFileUploadConfig and provideFileDropzoneConfig functions in a providers array.

import { provideFileDropzoneConfig, provideFileUploadConfig } from 'ng-primitives/file-upload';

bootstrapApplication(AppComponent, {
  providers: [
    provideFileUploadConfig({
      fileTypes: ['image/png', '.jpg'],
      multiple: true,
      dragAndDrop: false,
    }),
    provideFileDropzoneConfig({
      fileTypes: ['image/png', '.jpg'],
      multiple: true,
    }),
  ],
});

Any input set on a primitive takes precedence over the configured default.

NgpFileUploadConfig

NgpFileDropzoneConfig

Accessibility

The file upload primitive should be applied to a <button> element or another interactive element for keyboard accessibility. The file dropzone is a drag-and-drop target and is not keyboard accessible by default — ensure an alternative method (such as the file upload trigger) is always available.

Keyboard Interactions

• Enter / Space: Open the file selection dialog (when applied to a button).
• Ctrl / Cmd + V: Select files from the clipboard (when paste is enabled).