Angular file uploader
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
demo translate comments Oct 17, 2013
.gitignore add to npm Oct 19, 2015
.npmignore add to npm Oct 19, 2015
LICENSE Update Oct 2, 2013
bower.json Create bower.json Apr 1, 2014
oi.file.js #9 Во время drag-drop`а файлов на область в FF не добавляется класс о… Aug 7, 2014
package.json add to npm Oct 19, 2015

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:
    • - 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)