0.0.0 • Public • Published

    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)




    npm i oi.file

    DownloadsWeekly Downloads






    Last publish


    • tamtakoe