oi.file — AngularJS file uploader =======

Usage no npm install needed!

<script type="module">
  import oiFile from 'https://cdn.skypack.dev/oi.file';


oi.file — AngularJS file uploader

Русская документация

Key features

  • File selection from explorer/finder and by drag'n'drop
  • Validation
  • Image upload before posting to server (if browser supports FileReader)
  • Image upload via xhr and iframe (for older browsers)
  • Files data are embedded into a model, but can be read separately
  • Files are uploaded using POST method, each request per file
  • For AngularJS 1.2+, but there is oi.file.old.js for old versions

Demo, sandbox


Angular module dependency:

angular.module('myApp', ['oi.file']);

As a directive:

<!-- Uploading via explorer/finder -->
<input type="file" oi-file="options">

<!-- Uploading by dragging into drop area -->
<ul oi-file="options">
  <li ng-repeat="item in items">
    <img ng-src="{{item.thumb}}"> 

By the way, you can drop right onto the select files button

File upload setup in controller:

$scope.file = {} //Model
$scope.options = {
  //Called for each selected file
  change: function (file) {
      //file contains info about the uploaded file
      //uploading to server
      file.$upload('uploader.php', $scope.file)

Creating model element for each file

$scope.items = model
$scope.options = {
  change: function (file) {
    //Creating empty element for future file
    $scope.add(function (i, id) {
      //Uploading the file via FileReader before main server post
      //Uploading the file
      file.$upload('uploader.php' + id, $scope.items[i], {allowedType: ["jpeg", "jpg", "png"]})
        .catch(function (data) {
          //Removing element if something goes wrong

catch method is available starting from Angular 1.2. If you're using older versions, then use then(null, function (data) {...}) instead.

$preview and $upload return promises. See $q.

Third argument in $upload method is a validation params object. Upload module has validation function built-in, which can be overriden. Same way you can override the function of error handling.

Example with image resizing on client-side:

  .then(function (data) {
    //Image is read by this moment. Resizing it with canvas
    file.$upload('uploader.php', $scope.avatar)
  }, function (data) {
    //Image hasn't been read. Sending as is
    file.$upload('uploader.php', $scope.avatar)

Default settings can be overridden in a service variable oiFileConfig

Setting up

  • change function (file). Getting the file object. If it is null - doing nothing.

    • file {object} - File object, that contains info about selected file and methods:

      • $preview function (item, [field]) item -model, field - field, where the image in dataUrl format is written (writing here unless specified otherwise). Returns promises with success, error callbacks
      • $upload function (url, item, [permit]) url - upload script, item - model, permit - validation settings object (see below). Returns promises with success, error, notice callbacks

      In promises' callbacks $preview и $upload xhr is passed with additional fields: item: {...} model into which the uploading is performed and response: {...} server response, decodeed from JSON

  • validate function (file, permit). Files validation

    • file {object} - file object
    • permit {object} - validation params. Example:
      • allowedType: ["jpeg", "jpg", "png", "gif"], whitelist of extensions
      • maxNumberOfFiles: 100, maximum number of files
      • maxSize: 4194304, maximum file size
      • maxSpace: 104857600, maximum server storage space available
      • quantity: 3, files uploaded
      • space: 481208, storage place taken
      • errorBadType: "You can upload only: JPEG, JPG, PNG, GIF", Error messages...
      • errorBigSize: "The file is too big",
      • errorMaxQuantity: "Maximum number of uploaded files exceeded: 100",
      • errorMaxSize: "Only 2,3 МB of free space is left"
    • return {object} - array of error objects [{msg: 'error msg', code: 'код'}, {...}, ... ]
  • setError function (code, data). Error handling

    • code {string} - error code
    • data {object} - xhr with additional fields
      • item: {...}, model, into which the uploading is performed
      • response: {...}, server response, decoded from JSON
    • return {object} - object: {item: model, response: errors array}
  • url {string}. Default url to uploader script 'uploader.php'

  • fieldName {string}. $_FILES array key 'Files'

  • fileClass {string}. Draggable file class name 'dragover-file'

  • notFileClass {string}. Draggable non-file class name 'dragover-plain'

Fields added to model (for each file):

  • fileName {string}. File name 'filename'
  • fileThumb {string}. Thumbnail reference 'thumb',
  • fileSize {string}. File size 'size',
  • fileLoaded {string}. Loaded, bytes (will be removed in the end) 'loaded'
  • fileProgress {string}. Upload percentage (will be removed in the end) 'progress'
  • fileUploading {string}. Находится ли файл в процессе загрузки 'uploading'

Fields added to scope:

  • queue {string}. Upload queue 'uploading'. Contains a general options:
    • queue.total - all files size, bytes
    • queue.loaded - all files loaded, bytes
    • queue.progress - all files upload percentage
    • queue.all - number of uploaded files
    • queue.length - number of remaining files (native option)