Primitives

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.

Select or drag and drop files here.

Max file size: 10MB

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>

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.

Drag and drop files anywhere here!

But clicking won't open a file selection dialog.

Reusable Component

Create a file upload component that uses the NgpFileUpload directive.

import { Component } from '@angular/core';
import { FileUpload } from './file-upload';

@Component({
  selector: 'app-root',
  imports: [FileUpload],
  template: `
    <app-file-upload (selected)="onFilesSelected($event)" />
  `,
})
export default class App {
  onFilesSelected(files: FileList | null): void {
    if (files) {
      alert(`Selected ${files.length} files.`);
    }
  }
}

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.
  • componentSuffix: The suffix to apply to the generated component class name.
  • fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
  • exampleStyles: Whether to include example styles in the generated component file. Defaults to true.

API Reference

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

NgpFileUpload

A directive that allows you to turn any element into a file upload trigger.

  • Selector: [ngpFileUpload]
  • Exported As: ngpFileUpload
ngpFileUploadFileTypes
string[] | undefined

The accepted file types. This can be an array of strings or a comma-separated string. Accepted types can either be file extensions (e.g. `.jpg`) or MIME types (e.g. `image/jpeg`).

ngpFileUploadMultiple
boolean

Whether to allow multiple files to be selected.

ngpFileUploadDirectory
boolean

Whether to allow the user to select directories.

ngpFileUploadDragDrop
boolean

Whether drag-and-drop is enabled.

ngpFileUploadDisabled
boolean

Whether the file upload is disabled.

ngpFileUploadSelected
FileList | null

Emits when the user selects files.

ngpFileUploadCanceled
void

Emits when the user cancel the file selection.

ngpFileUploadRejected
void

Emits when uploaded files are rejected because they do not match the allowed {@link fileTypes}.

ngpFileUploadDragOver
boolean

Emits when the user drags a file over the file upload.

Data Attributes

Attribute Description
data-hover Applied when the element is hovered.
data-focus-visible Applied when the element is focus visible.
data-press Applied when the element is pressed.
data-dragover Applied when a file is dragged over the element.
data-disabled Applied when the element is disabled.

NgpFileDropzone

Capture files dropped on the element.

  • Selector: [ngpFileDropzone]
  • Exported As: ngpFileDropzone
ngpFileDropzoneFileTypes
string[] | undefined

The accepted file types. This can be an array of strings or a comma-separated string. Accepted types can either be file extensions (e.g. `.jpg`) or MIME types (e.g. `image/jpeg`).

ngpFileDropzoneMultiple
boolean

Whether to allow multiple files to be selected.

ngpFileDropzoneDirectory
boolean

Whether to allow the user to select directories.

ngpFileDropzoneDisabled
boolean

Whether the file upload is disabled.

ngpFileDropzoneSelected
FileList | null

Emits when the user selects files.

ngpFileDropzoneRejected
void

Emits when uploaded files are rejected because they do not match the allowed {@link fileTypes}.

ngpFileDropzoneDragOver
boolean

Emits when the user drags a file over the file upload.

Data Attributes

Attribute Description
data-hover Applied when the element is hovered.
data-dragover Applied when a file is dragged over the element.
data-disabled Applied when the element is disabled.

Copyright © 2025 Angular Primitives