Bootstrap File Input Options

Thankful to Krajee!
to get more out of us.

All the options to the bootstrap file input plugin can be passed typically via the javascript object at plugin initialization. Depending on your need, these options can also be configured as HTML5 data attributes on the native file input (on which the plugin is initialized). The plugin supports the following options.

Tip

Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)

language

string, language configuration for the plugin to enable the plugin to display messages for your locale (you must set the ISO code for the language). You can have multiple language widgets on the same page. The locale JS file for the language code must be defined as mentioned in the translations section. The file must be loaded after fileinput.js.

theme

string, theme to use for the plugin (will default to the inbuilt theme if not set). With release v4.3.2, the fileinput plugin supports advanced theming and ability to have separate themes for multiple widgets on the same page. To do this, follow these simple steps:

  • Load respective theme JS file(s) that you need (e.g. themes/fa/fa.js for Font Awesome theme). The theme file(s) must be loaded after the fileinput.js.

  • Set the theme property in the plugin to the theme you need and which you have setup in your theme configuration JS file above (e.g. 'fa').

  • The plugin will automatically read the theme configuration for the theme name from $fileinputThemes['<theme-name>'] from the JS file (e.g. via $fileinputThemes['<theme-name>']).

  • The plugin will automatically also prepend the CSS selector theme-<theme-name> to the file input container, so that you can override your styles. The CSS for such themes can be submitted by community in themes/THEME_NAME folder of the repo.

  • You can additionally load any theme specific CSS files if needed.

Note

Currently the plugin includes the Font Awesome, Glyphicons, Krajee Explorer, and Krajee Explorer Font Awesome themes. More advanced themes may be added in future or can be contributed here by the community.

required

boolean, whether file selection is mandatory before upload (for ajax) or submit of the form (for non-ajax). When set to true, and if files are not selected before upload, this will show the error message as set in msgFilerequired. Defaults to false.

Check the required validation demos for understanding details on how to use this property.

rtl

boolean, whether to orient the widget in Right-To-Left (RTL) mode. To view RTL orientation you must set this to true and also must load the css/fileinput-rtl.css file after the css/fileinput.css on your page for RTL styling. Defaults to false.

Check the RTL usage demo for understanding details on how to use this property.

hiddenThumbnailContent

boolean, whether to hide the preview content (image, pdf content, text content, etc.) within the thumbnail. Defaults to false. When set to true, only the file name and file size as defined in the thumbnail footer layout template will be displayed.

Check the Glyphicon Theme Alternate Demo for understanding details on how to use this property.

showCaption

boolean, whether to display the file caption. Defaults to true.

showPreview

boolean, whether to display the file preview. Defaults to true.

showRemove

boolean, whether to display the file remove/clear button. Defaults to true.

showUpload

boolean, whether to display the file upload button. Defaults to true. This will default to a form submit button for a non-ajax scenario when the uploadUrl is not specified. For an ajax upload scenario, this will use the uploadUrl as a link.

showCancel

boolean, whether to display the file upload cancel button. Defaults to true. This will be only enabled and displayed when an AJAX upload is in process.

showClose

boolean, whether to display the close icon in the preview. Defaults to true. This will be only parsed when showPreview is true or when you are using the {close} tag in your preview templates.

showUploadedThumbs

boolean, whether to persist display of the uploaded file thumbnails in the preview window (for ajax uploads) until the remove/clear button is pressed. Defaults to true. When set to false, a next batch of files selected for upload will clear these thumbnails from preview.

showBrowse

boolean, whether to display the file browse button. Defaults to true.

browseOnZoneClick

boolean, whether to enable file browse/select on clicking of the preview zone. Defaults to false.

autoReplace

boolean, whether to automatically replace the files in the preview after the maxFileCount limit is reached and a new set of file(s) is/are selected. This will only work if a valid maxFileCount is set. Defaults to false.

autoOrientImage

boolean, whether to automatically orient the image for display based on EXIF orientation tag (i.e. rotate or mirror flip horizontally/vertically). This property will affect only the image preview and is applicable only for JPEG images selected from client before upload. It does not alter the file sent to server. Thus, it will not be applicable for images shown in initialPreview. Defaults to true.

Note that only jpeg files will be detected for auto orientation.

You can see how this works in the auto image orientation demo.

captionClass

string, any additional CSS class to append to the caption container.

previewClass

string, any additional CSS class to append to the preview container.

mainClass

string, any additional CSS class to append to the main plugin container that will render the caption and the browse, remove, and upload buttons. Defaults to file-caption-main.

frameClass

string, the CSS class to be additionally applied to each file thumbnail frame. Defaults to krajee-default.

purifyHtml

boolean, whether to purify HTML content displayed for HTML content type in preview. Defaults to true. This functionality will need the DomPurify plugin by cure53 to be loaded.

fileSizeGetter

boolean, the callback to generate the human friendly filesize based on the bytes parameter. If not set this will default to the following callback:

function (bytes) {
    var i = Math.floor(Math.log(bytes) / Math.log(1024)),
        sizes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
    return (bytes / Math.pow(1024, i)).toFixed(2) * 1 + ' ' + sizes[i];
}

initialPreview

string | array the initial preview content to be displayed. You can pass the minimal HTML markup for displaying your image, text, or file. If set as a string, this will display a single file in the initial preview if there is no delimiter. You can set a delimiter (as defined in initialDelimiter) to show multiple files in initial preview. If set as an array, it will display all files in the array as an initial preview (useful for multiple file upload scenarios).

The following CSS classes will need to be added for displaying each file type as per the plugin style theme:

  • image files: Include CSS class file-preview-image
  • text files: Include CSS class file-preview-text
  • other files: Include CSS class file-preview-other

Examples of how you can setup various files for initial preview:

// for image files
initialPreview: [
    "<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",
    "<img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>",
],

// for text files
initialPreview: "<div class='file-preview-text' title='NOTES.txt'>" +
    "This is the sample text file content upto wrapTextLength of 250 characters" +
    "<span class='wrap-indicator' onclick='$(\"#show-detailed-text\").modal(\"show\")' title='NOTES.txt'>[…]</span>" +
    "</div>"

// for other files
initialPreview: "<div class='file-preview-text'>" +
    "<h3><i class='glyphicon glyphicon-file'></i></h3>" +
    "Filename.xlsx" + "</div>"

initialPreviewCount

int, the count of initial preview items that will be added to the count of files selected in preview. This is applicable when displaying the right caption, when overwriteInitial is set to false.

initialPreviewDelimiter

string, the delimiter to be used for splitting the initial preview content as individual file thumbnails (applicable only if initialPreview is passed as a string, instead of array). Defaults to *$$*.

initialPreviewAsData

boolean, whether the initial preview content set is to be parsed as data instead of raw markup. Defaults to false for backward compatibility (prior to v4.3.2).

initialPreviewFileType

string, one of the file template types as configured within the keys in previewSettings. This is useful to identify the template to be used to display the particular file's content. Defaults to image.

initialPreviewConfig

array, the configuration for setting up important properties for each initialPreview item (that is setup as part of initialPreview). Each element in the array should be an object/associative array consisting of the following keys:

  • type: string, one of the file template types as configured within the keys in previewSettings. This will override the initialPreviewFileType setting. This is useful to identify the template to be used to display the particular file's content.

  • filetype: string, file mime type to identify the content. Useful for certain file templates like audio or video (e.g. video/mp4).

  • size: float, the size of the file in BYTES which will be displayed using the size layout template. If not set or if it cannot be parsed as a float number, then a blank string will be displayed.

  • previewAsData: boolean, whether to parse this preview content as a data input instead of a raw markup source. This will override the initialPreviewAsData setting.

  • caption: string, the caption or filename to display for each initial preview item content.

  • width: string, the CSS width of the image/content displayed.

  • url: string, the URL for deleting the image/content in the initial preview via AJAX post response. This will default to deleteUrl if not set.

  • key: string | object, the key that will be passed as data to the url via AJAX POST.

  • frameClass: string, the additional frame css class to set for the file's thumbnail frame.

  • frameAttr: object, the HTML attribute settings (set as key:value pairs) for the thumbnail frame.

  • extra: object | function, the extra data that will be passed as data to the initial preview delete url/AJAX server call via POST. This will default to deleteExtraData if not set.

An example configuration of initialPreviewConfig (for the previously set initialPreviewContent) can be:

// setup initial preview with data keys
initialPreview: [
    "<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",
    "<img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>",
],
// initial preview configuration
initialPreviewConfig: [
    {
        caption: 'desert.jpg',
        width: '120px',
        url: '/localhost/avatar/delete',
        key: 100,
        extra: {id: 100}
    },
    {
        caption: 'jellyfish.jpg', 
        width: '120px', 
        url: '/localhost/avatar/delete', 
        key: 101, 
        frameClass: 'my-custom-frame-css',
        frameAttr: {
            style: 'height:80px',
            title: 'My Custom Title',
        },
        extra: function() { 
            return {id: $("#id").val()};
        },
    }
]

Note that initialPreview and initialPreviewConfig can also be setup in an easier way without rendering the entire markup but just passing the data. For this the initialPreviewAsData property must be set to true, and the preview will be rendered using the templates for the initial preview types. Within the initialPreviewConfig, the type key will identify the preview file type for the data passed.

For example, initial preview can be setup as a data in the following way:

initialPreview: [
    // IMAGE DATA
   'http://lorempixel.com/800/460/business/1',
    // IMAGE RAW MARKUP
    '<img src="http://lorempixel.com/800/460/business/2" class="kv-preview-data file-preview-image" style="height:160px">',
    // TEXT DATA
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec ut mauris ut libero fermentum feugiat eu et dui. Mauris condimentum rhoncus enim, sed semper neque vestibulum id. Nulla semper, turpis ut consequat imperdiet, enim turpis aliquet orci, eget venenatis elit sapien non ante. Aliquam neque ipsum, rhoncus id ipsum et, volutpat tincidunt augue. Maecenas dolor libero, gravida nec est at, commodo tempor massa. Sed id feugiat massa. Pellentesque at est eu ante aliquam viverra ac sed est.",
    // PDF DATA
    'http://kartik-v.github.io/bootstrap-fileinput-samples/samples/pdf-sample.pdf',
    // VIDEO DATA
    "http://kartik-v.github.io/bootstrap-fileinput-samples/samples/small.mp4",
],
initialPreviewAsData: true, // defaults markup  
initialPreviewConfig: [
    {caption: "Business 1.jpg", size: 762980, url: "$urlD", key: 11},
    {previewAsData: false, size: 823782, caption: "Business 2.jpg", url: "$urlD", key: 13}, 
    {caption: "Lorem Ipsum.txt", type: "text", size: 1430, url: "$urlD", key: 12}, 
    {type: "pdf", size: 8000, caption: "PDF Sample.pdf", url: "$urlD", key: 14}, 
    {type: "video", size: 375000, filetype: "video/mp4", caption: "Krajee Sample.mp4", url: "$urlD", key: 15},  
],

Note

The ajax delete action will send the following data to server via POST:

  • key: the key setting as setup in initialPreviewConfig['key']

  • extra: the extra data passed either via initialPreviewConfig['extra'] OR deleteExtraData if former is not set.

initialPreviewShowDelete

boolean, whether the delete button will be displayed for each thumbnail that has been created with initialPreview.

removeFromPreviewOnError

boolean, whether the file thumbnail should be removed from preview on error. Defaults to false.

previewThumbTags

array, this will be a list of tags used in thumbnail templates that will be replaced dynamically within the thumbnail markup, when the thumbnail is rendered. For example:

// change thumbnail footer template
layoutTemplates.footer = '<div class="file-thumbnail-footer">\n' +
'    <div class="file-caption-name">{caption}{size}</div>\n' +
'    {CUSTOM_TAG_NEW}\n' +
'    {CUSTOM_TAG_INIT}\n' +
'    {actions}\n' +
'</div>';

// set preview template tags
previewThumbTags = {
    '{CUSTOM_TAG_NEW}': '<span class="custom-css">CUSTOM MARKUP</span>',
    '{CUSTOM_TAG_INIT}': ' '
};

initialPreviewThumbTags

array, this is an extension of previewThumbTags specifically for initial preview content - but will be configured as an array of objects corresponding to each initial preview thumbnail. The initial preview thumbnails set via initialPreview will read this configuration for replacing tags. Extending example above:

// change thumbnail footer template
layoutTemplates.footer = '<div class="file-thumbnail-footer">\n' +
'    <div class="file-caption-name">{caption}{size}</div>\n' +
'    {CUSTOM_TAG_NEW}\n' +
'    {CUSTOM_TAG_INIT}\n' +
'    {actions}\n' +
'</div>';

// setup initial preview with data keys
initialPreview: [
    "<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>",
    "<img src='/images/jellyfish.jpg' class='file-preview-image' alt='Jelly Fish' title='Jelly Fish'>",
],

// set initial preview template tags
initialPreviewThumbTags = {
    '{CUSTOM_TAG_NEW}': ' ',
    '{CUSTOM_TAG_INIT}': '<span class="custom-css">CUSTOM MARKUP</span>'
};

deleteExtraData

object | function the extra data that will be passed as data to the initial preview delete url/AJAX server call via POST. This will be overridden by the initialPreviewConfig['extra'] property. This property is only applicable for ajax deletions in initial preview and when you have set a value for initialPreviewConfig['url'] or deleteUrl.

This can be setup either as an object (associative array of keys and values) or as a function callback. As an object, it can be set for example as:

  {id: 100, value: '100 Details'}

As a function callback, it can be setup for example as:

function() {
    var obj = {};
    $('.your-form-class').find('input').each(function() {
        var id = $(this).attr('id'), val = $(this).val();
        obj[id] = val;
    });
    return obj;
}

Note

The ajax delete action will send the following data to server via POST:

  • key: the key setting as setup in initialPreviewConfig['key']

  • any other extra data passed as key: value pairs either via initialPreviewConfig['extra'] OR deleteExtraData if former is not set.

deleteUrl

string, the URL for deleting the image/content in the initial preview via AJAX post response. This will be overridden by the initialPreviewConfig['url'] property.

initialCaption

string, the initial preview caption text to be displayed. If you do not set a value here and initialPreview is set to true this will default to "{preview-file-count} files selected", where {preview-file-count} is the count of the files passed in initialPreview.

overwriteInitial

boolean, whether you wish to overwrite the initial preview content and caption setup. This defaults to true, whereby, any initialPreview content set will be overwritten, when new file is uploaded or when files are cleared. Setting it to false will help displaying a saved image or file from database always - useful especially when using the multiple file upload feature.

layoutTemplates

object the templates configuration for rendering each part of the layout. You can set the following templates to control the widget layout:

  • main1: the template for rendering the widget with caption.

  • main2: the template for rendering the widget without caption.

  • preview: the template for rendering the preview.

  • fileIcon: the icon to render before the caption text.

  • size: the template to display the file size in the thumbnails. The tag {sizeText} should be used to render the size data.

  • caption: the template for rendering the caption.

  • modal: the template for rendering the modal (for file content preview zooming).

  • progress: the template for the progress bar when upload is in progress (for batch/mass uploads and within each preview thumbnail for async/single uploads). The upload progress bar when displayed within each thumbnail will be wrapped inside a container having a CSS class of `file-thumb-progress`. The following tags will be parsed and replaced automatically:

    • {percent}: will be replaced with the upload progress percentage.

  • footer: the template for the footer section of each file preview thumbnail. The following tags will be parsed and replaced automatically:

    • {actions}: will be replaced with the output of the actions template.

  • actions: the template for the file action buttons to be displayed within the thumbnail footer. The following tags will be parsed and replaced automatically:

    • {upload}: will be replaced with the output of the actionUpload template.

    • {download}: will be replaced with the output of the actionDownload template.

    • {delete}: will be replaced with the output of the actionDelete template.

  • actionDelete: the template for the file delete action button within the thumbnail footer. The following tags will be parsed and replaced automatically:

    • {removeClass}: the css class for the remove button. Will be replaced with the removeClass set within fileActionSettings.

    • {removeIcon}: the icon for the remove button. Will be replaced with the removeIcon set within fileActionSettings.

    • {removeTitle}: the title to display on hover for the remove button. Will be replaced with the removeTitle set within fileActionSettings.

    • {dataUrl}: the HTML5 data element data-url and its URL value for deleting the file thumbnail for initialPreview content only. The URL value will be parsed from the url set within initialPreviewConfig. So if the URL is set to http://your-delete-api, then this tag will be replaced to data-url="http://your-delete-api".

    • {dataKey}: the HTML5 data element data-key and the value of the key (additional data) that will be passed to the URL above via POST to the AJAX call. The key value will be parsed from the key set within initialPreviewConfig. So if the key is set to 100, then this tag will be replaced to data-key=100.

  • actionUpload: the template for the file upload action button within the thumbnail footer.

    • {uploadClass}: the css class for the upload button. Will be replaced with the uploadClass set within fileActionSettings.

    • {uploadIcon}: the icon for the upload button. Will be replaced with the uploadIcon set within fileActionSettings.

    • {uploadTitle}: the title to display on hover for the upload button. Will be replaced with the uploadTitle set within fileActionSettings.

  • actionDownload: the template for the file download action button within the thumbnail footer.

    • {downloadClass}: the css class for the download button. Will be replaced with the downloadClass set within fileActionSettings.

    • {downloadIcon}: the icon for the download button. Will be replaced with the downloadIcon set within fileActionSettings.

    • {downloadTitle}: the title to display on hover for the download button. Will be replaced with the downloadTitle set within fileActionSettings.

    • {downloadUrl}: the url to be used to trigger the download of the selected thumbnail. This will be derived from the downloadUrl property for the thumbnail frame within initialPreviewConfig or if this is not set, will be auto derived from the initialPreviewDownloadUrl setting. If neither are set, or the url is set to false, then the download action button will not be displayed.

    • {caption}: the name of the file that will be downloaded. Will be derived from the filename property for the thumbnail frame within initialPreviewConfig or if that is not available, will use the caption property for the thumbnail frame within initialPreviewConfig.

      NOTE The caption name to download the file will be displayed using the HTML5 download attribute for the download link tag. The feature is supported only on specific browsers. Also the link to download the files must be on the same domain to prevent cross origin resource sharing (CORS) issue.

The main1 and main2 templates would automatically parse the following tags for replacement:

  • {class}: the CSS class as set in the mainClass property.

  • {close}: will be replaced with the close (cross) icon (by default on top right of the preview window). The layout template to control this markup is layoutTemplates.close.

  • {preview}: the content parsed by the previewTemplate and will be displayed only if showPreview is true.

  • {caption}: the content parsed by the captionTemplate and will be displayed only if showCaption is true.

  • {size}: the content parsed by the layoutTemplates.size.

  • {remove}: the file remove/clear button and will be displayed only if showRemove is true.

  • {upload}: the file upload button and will be displayed only if showUpload is true.

  • {cancel}: the file upload cancel button that will be displayed when AJAX upload is in process to abort the AJAX upload.

  • {browse}: the main file browse button to select your files for input.

The progress template would automatically parse the following tags for replacement:

The preview and caption templates can understand the following special tags which will be replaced:

The layoutTemplates if not set will default to:

{
    main1: '{preview}\n' +
        '<div class="kv-upload-progress kv-hidden"></div><div class="clearfix"></div>\n' +
        '<div class="input-group {class}">\n' +
        '  {caption}\n' +
        '  <div class="input-group-btn">\n' +
        '    {remove}\n' +
        '    {cancel}\n' +
        '    {upload}\n' +
        '    {browse}\n' +
        '  </div>\n' +
        '</div>',
    main2: '{preview}\n<div class="kv-upload-progress hide"></div>\n{remove}\n{cancel}\n{upload}\n{browse}\n',
    preview: '<div class="file-preview {class}">\n' +
        '    {close}\n' +
        '    <div class="close fileinput-remove">×</div>\n' +
        '    <div class="{dropClass}">\n' +
        '    <div class="file-preview-thumbnails">\n' +
        '    </div>\n' +
        '    <div class="clearfix"></div>' +
        '    <div class="file-preview-status text-center text-success"></div>\n' +
        '    <div class="kv-fileinput-error"></div>\n' +
        '    </div>\n' +
        '</div>',
    icon: '<span class="glyphicon glyphicon-file kv-caption-icon"></span>',
    caption: '<div class="file-caption form-control {class}" tabindex="500">\n' +
        '  <span class="file-caption-icon"></span>\n' +
        '  <input class="file-caption-name" onkeydown="return false;" onpaste="return false;">\n' +
        '</div>',
    btnDefault: '<button type="{type}" tabindex="500" title="{title}" class="{css}"{status}>{icon}{label}</button>',
    btnLink: '<a href="{href}" tabindex="500" title="{title}" class="{css}"{status}>{icon}{label}</a>',
    btnBrowse: '<div tabindex="500" class="{css}"{status}>{icon}{label}</div>',
    modalMain: '<div id="kvFileinputModal" class="file-zoom-dialog modal fade" tabindex="-1" aria-labelledby="kvFileinputModalLabel"></div>',
    modal: '<div class="modal-dialog modal-lg{rtl}" role="document">\n' +
        '  <div class="modal-content">\n' +
        '    <div class="modal-header">\n' +
        '      <div class="kv-zoom-actions pull-right">{toggleheader}{fullscreen}{borderless}{close}</div>\n' +
        '      <h3 class="modal-title">{heading} <small><span class="kv-zoom-title"></span></small></h3>\n' +
        '    </div>\n' +
        '    <div class="modal-body">\n' +
        '      <div class="floating-buttons"></div>\n' +
        '      <div class="kv-zoom-body file-zoom-content"></div>\n' + '{prev} {next}\n' +
        '    </div>\n' +
        '  </div>\n' +
        '</div>\n',
    progress: '<div class="progress">\n' +
        '    <div class="progress-bar progress-bar-success progress-bar-striped text-center" role="progressbar" aria-valuenow="{percent}" aria-valuemin="0" aria-valuemax="100" style="width:{percent}%;">\n' +
        '        {status}\n' +
        '     </div>\n' +
        '</div>',
    footer: '<div class="file-thumbnail-footer">\n' +
        '    <div class="file-caption-name" style="width:{width}">{caption}</div>\n' +
        '    {progress} {actions}\n' +
        '</div>',
    actions: '<div class="file-actions">\n' +
        '    <div class="file-footer-buttons">\n' +
        '        {upload} {download} {delete} {zoom} {other}' +
        '    </div>\n' +
        '    {drag}\n' +
        '    <div class="file-upload-indicator" title="{indicatorTitle}">{indicator}</div>\n' +
        '    <div class="clearfix"></div>\n' +
        '</div>',
    actionDelete: '<button type="button" class="kv-file-remove {removeClass}" title="{removeTitle}"{dataUrl}{dataKey}>{removeIcon}</button>\n',
    actionUpload: '<button type="button" class="kv-file-upload {uploadClass}" title="{uploadTitle}">{uploadIcon}</button>\n',
    actionDownload: '<button type="button" class="{downloadClass}" title="{downloadTitle}" data-url="{downloadUrl}" data-caption="{caption}">{downloadIcon}</button>\n',
    actionZoom: '<button type="button" class="kv-file-zoom {zoomClass}" title="{zoomTitle}">{zoomIcon}</button>',
    actionDrag: '<span class="file-drag-handle {dragClass}" title="{dragTitle}">{dragIcon}</span>'
}

The following templates will be used in rendering the main buttons for upload, remove, cancel, and browse.

  • btnDefault: The template for upload, remove, and cancel buttons.

  • btnLink: The template for upload button when used with ajax (i.e. when uploadUrl is set).

  • btnBrowse: The template for the browse button.

The following tags will be parsed and auto replaced in the above button templates:

  • {type}: the HTML button type, defaults to button for most buttons and submit for form based uploads.

  • {title}: the title to display on button hover.

  • {css}: the CSS class for the button. This is derived from settings for uploadClass or removeClass or cancelClass or browseClass.

  • {status}: the disabled status for the button if available (else will be blank).

  • {icon}: the button icon as identified by uploadIcon or removeIcon or cancelIcon or browseIcon.

  • {label}: the button label as identified by uploadLabel or removeLabel or cancelLabel or browseLabel.

  • {href}: applicable only for Upload button for ajax uploads and will be replaced with the uploadUrl property.

previewTemplates

object the templates configuration for rendering each preview file type. The following file types are recognized:

  • image: the preview template for image files.

  • text: the preview template for text files.

  • html: the preview template for html files.

  • video: the preview template for video files (supported by HTML 5 video tag).

  • audio: the preview template for audio files (supported by HTML 5 audio tag).

  • flash: the preview template for flash files (supported currently on webkit browsers).

  • object: the preview template for all other files - by default treated as object. To disable this behavior, configure the allowedPreviewTypes property.

  • generic: this template is used ONLY for rendering the initialPreview markup content passed directly as a raw format.

The following tags will be parsed and replaced in each of the templates:

  • {rtl}: will be set to kv-rtl css class when rtl is set to true, else will be a empty string.

  • {fileindex}: will be replaced with the sequential index of the file within the selected file stack

  • {previewId}: will be replaced with the generated HTML identifier for the file preview thumbnail frame

  • {template}: the template key name

  • {frameClass}: will be replaced by the frameClass setting

  • {caption}: will be replaced by the file caption / file name

  • {style}: will be replaced by the CSS style markup based on the settings in previewSettings or previewSettingsSmall

  • {data}: will be replaced by the raw file data when files are selected on client, or data source set via initialPreview for initial preview content

  • {footer}: will be replaced with the thumbnail footer that displays the actions .

  • {content}: this is applicable only for the generic template. It will be replaced with the raw HTML markup as set in initialPreview. None of the above tags will be parsed for the generic template.

As noted, if you are coming from an earlier release (before v2.4.0), all preview templates have now been combined into one property, instead of separate templates for image, text etc.

NOTE: when setting your own preview templates, the following CSS classes are mandatory to identify elements within each file preview template:

  • file-preview-frame: CSS class to identify each preview thumbnail frame container

  • kv-file-content: CSS class to identify the display container for the file content

  • kv-preview-data: CSS class to identify the element containing the data source (and the {data} tag) for each file type

The other CSS classes that control styling of each preview thumbnail is based on each file type and identified by helper CSS classes like file-preview-image, file-preview-text, file-preview-html etc.

{
    generic: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   {content}\n' +
        '   {footer}\n' +
        '</div>\n',
    image: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   <div class="kv-file-content">' +
        '       <img src="{data}" class="kv-preview-data file-preview-image" title="{caption}" alt="{caption}" {style}>\n' +
        '   </div>\n' +
        '   {footer}\n' +
        '</div>\n',
    text: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   <div class="kv-file-content">' +
        '       <textarea class="kv-preview-data file-preview-text" title="{caption}" readonly {style}>{data}</textarea>' +
        '   </div>\n' +
        '   {footer}\n' +
        '</div>',
    office: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   <div class="kv-file-content">' +
        '      <iframe class="kv-preview-data file-preview-office" src="https://docs.google.com/gview?url={data}&embedded=true" {style}></iframe>\n' +
        '       <img src="{data}" class="kv-preview-data file-preview-image" title="{caption}" alt="{caption}" {style}>\n' +
        '   </div>\n' +
        '   {footer}\n' +
        '</div>\n',
    html: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   <div class="kv-file-content">' +
        '       <div class="kv-preview-data file-preview-html" title="{caption}" {style}>{data}</div>\n' +
        '   </div>\n' +
        '   {footer}\n' +
        '</div>',
    video: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}" title="{caption}">\n' +
        '   <div class="kv-file-content">' +
        '       <video class="kv-preview-data file-preview-video" controls {style}>\n' +
        '           <source src="{data}" type="{type}">\n' + DEFAULT_PREVIEW + '\n' +
        '       </video>\n' +
        '   </div>\n' +
        '   {footer}\n' +
        '</div>\n',
    audio: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}" title="{caption}" '
            + STYLE_SETTING + '>\n' +
        '   <div class="kv-file-content">' +      
        '        <audio class="kv-preview-data file-preview-audio" controls {style}>\n' +
        '            <source src="{data}" type="{type}">\n' + DEFAULT_PREVIEW + '\n' +
        '        </audio>\n' +
        '   </div>\n' +
        '   {footer}\n' +
        '</div>\n',
    pdf: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   <div class="kv-file-content">' +
        '       <embed class="kv-preview-data file-preview-pdf" src="{data}" type="application/pdf" {style}>\n',
        '   </div>\n' +
        '   {footer}\n' +
        '</div>',
    flash: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}">\n' +
        '   <div class="kv-file-content">' +
        '       <embed class="kv-preview-data file-preview-flash" src="{data}" type="application/flash" {style}>\n',
        '   </div>\n' +
        '   {footer}\n' +
        '</div>',
    object: '<div class="file-preview-frame" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}" title="{caption}" {style}>\n' +
        '   <div class="kv-file-content">' +
        '       <object  class="kv-preview-data file-preview-object file-object" data="{data}" type="{type}" {style}>\n' +
        '          <param name="movie" value="{caption}" />\n' + OBJECT_PARAMS + '\n' + DEFAULT_PREVIEW + '\n' +
        '       </object>\n' + 
        '   </div>\n' +
        '   {footer}\n' +
        '</div>',
    other: '<div class="file-preview-frame{frameClass}" id="{previewId}" data-fileindex="{fileindex}" data-template="{template}"' +
        ' title="{caption}">\n' +
        '   <div class="kv-file-content">' +
        '       <div class="kv-preview-data file-preview-other-frame" {style}>\n' + DEFAULT_PREVIEW + '\n' +
        '       </div>\n' +
        '   </div>\n' +
        '   <div class="file-preview-other-footer">{footer}</div>\n' +
        '</div>'
}

The values of the constants used in the above templates are as follows:

OBJECT_PARAMS = '      <param name="controller" value="true" />\n' +
    '      <param name="allowFullScreen" value="true" />\n' +
    '      <param name="allowScriptAccess" value="always" />\n' +
    '      <param name="autoPlay" value="false" />\n' +
    '      <param name="autoStart" value="false" />\n'+
    '      <param name="quality" value="high" />\n',
DEFAULT_PREVIEW = '<div class="file-preview-other">\n' +
    '   <span class="{previewFileIconClass}">{previewFileIcon}</span>\n' +
    '</div>'

where:

previewSettings

object the CSS style settings for rendering each preview file type set above. This is by default setup as following:

{
    image: {width: "auto", height: "auto", 'max-width': "100%", 'max-height': "100%"},
    html: {width: "213px", height: "160px"},
    text: {width: "213px", height: "160px"},
    office: {width: "213px", height: "160px"},
    video: {width: "213px", height: "160px"},
    audio: {width: "100%", height: "30px"},
    flash: {width: "213px", height: "160px"},
    object: {width: "213px", height: "160px"},
    pdf: {width: "213px", height: "160px"},
    other: {width: "213px", height: "160px"}
}

previewSettingsSmall

object, similar to previewSettings, but the CSS styles are applied only for small devices with screen width less than 400px. This is by default setup as following:

{
    image: {width: "auto", height: "auto", 'max-width': "100%", 'max-height': "100%"},
    html: {width: "100%", height: "160px"},
    text: {width: "100%", height: "160px"},
    office: {width: "100%", height: "160px"},
    video: {width: "100%", height: "auto"},
    audio: {width: "100%", height: "30px"},
    flash: {width: "100%", height: "auto"},
    object: {width: "100%", height: "auto"},
    pdf: {width: "100%", height: "160px"},
    other: {width: "100%", height: "160px"}
}

previewZoomSettings

object, the configuration of HTML attributes for the content displayed in the zoomed modal preview. The configuration is similar to previewSettings, however you can in this property set other HTML attributes beyond width and height. This property will override the configuration in previewSettings. You can set all CSS styling attributes as supported by HTML style attribute. Defaults to the following configuration for each file type:

{
    image: {width: "auto", height: "auto", 'max-width': "100%",'max-height': "100%"},
    html: {width: "100%", height: "100%", 'min-height': "480px"},
    text: {width: "100%", height: "100%", 'min-height': "480px"},
    office: {width: "100%", height: "100%", 'max-width': "100%", 'min-height': "480px"},
    video: {width: "auto", height: "100%", 'max-width': "100%"},
    audio: {width: "100%", height: "30px"},
    flash: {width: "auto", height: "480px"},
    object: {width: "auto", height: "480px"},
    pdf: {width: "100%", height: "100%", 'min-height': "480px"},
    other: {width: "auto", height: "100%", 'min-height': "480px"}
}

previewZoomButtonIcons

object, the icons to be displayed for the various zoom control buttons in the detailed preview. The following buttons can be set:

  • prev: button to navigate to the PREVIOUS file content in the modal preview

  • next: button to navigate to the NEXT file content in the modal preview

  • toggleheader: button to toggle display and slide out/in the modal header

  • fullscreen: button to toggle zoomed preview to full screen display

  • borderless: button to toggle preview to a border less maximized state (only difference from fullscreen button is that it does not set the browser to a native full screen mode)

  • close: button to close the modal zoom preview dialog

The previewZoomButtonIcons defaults to the following configuration:

{
    prev: '<i class="glyphicon glyphicon-triangle-left"></i>',
    next: '<i class="glyphicon glyphicon-triangle-right"></i>',
    toggleheader: '<i class="glyphicon glyphicon-resize-vertical"></i>',
    fullscreen: '<i class="glyphicon glyphicon-fullscreen"></i>',
    borderless: '<i class="glyphicon glyphicon-resize-full"></i>',
    close: '<i class="glyphicon glyphicon-remove"></i>'
}

previewZoomButtonClasses

object, the CSS classes to be set for the zoom control buttons in the detailed preview. The following buttons can be set:

  • prev: button to navigate to the PREVIOUS file content in the modal preview

  • next: button to navigate to the NEXT file content in the modal preview

  • toggleheader: button to toggle display and slide out/in the modal header

  • fullscreen: button to toggle zoomed preview to full screen display

  • borderless: button to toggle preview to a border less maximized state (only difference from fullscreen button is that it does not set the browser to a native full screen mode)

  • close: button to close the modal zoom preview dialog

The previewZoomButtonClasses defaults to the following configuration:

{
    prev: 'btn btn-navigate',
    next: 'btn btn-navigate',
    toggleheader: 'btn btn-kv btn-default btn-outline-secondary',
    fullscreen: 'btn btn-kv btn-default btn-outline-secondary',
    borderless: 'btn btn-kv btn-default btn-outline-secondary',
    close: 'btn btn-kv btn-default btn-outline-secondary'
}

preferIconicPreview

boolean, whether to force iconic preview of file thumbnails in the preview zone, by using the configuration for previewFileIconSettings and previewFileExtSettings. Defaults to false. If set to true, it will try to force an iconic file thumbnail preview if possible.

preferIconicZoomPreview

boolean, whether to force iconic preview of file thumbnails in the detailed zoom preview zone, by using the configuration for previewFileIconSettings and previewFileExtSettings. Defaults to false. If set to true, it will try to force an iconic preview for detailed zoom content if possible.

previewZoomButtonTitles

object, the titles to be set for the zoom control buttons in the detailed preview. The following buttons can be set:

  • prev: button to navigate to the PREVIOUS file content in the modal preview

  • next: button to navigate to the NEXT file content in the modal preview

  • toggleheader: button to toggle display and slide out/in the modal header

  • fullscreen: button to toggle zoomed preview to full screen display

  • borderless: button to toggle preview to a border less maximized state (only difference from fullscreen button is that it does not set the browser to a native full screen mode)

  • close: button to close the modal zoom preview dialog

The previewZoomButtonClasses defaults to the following configuration:

{
    prev: 'View previous file',
    next: 'View next file',
    toggleheader: 'Toggle header',
    fullscreen: 'Toggle full screen',
    borderless: 'Toggle borderless mode',
    close: 'Close detailed preview'
}

allowedFileTypes

array the list of allowed file types for upload. This by default is set to null which means the plugin supports all file types for upload. If an invalid file type is found, then a validation error message as set in msgInvalidFileType will be raised. The following types as set in fileTypeSettings are available for setup.

['image', 'html', 'text', 'video', 'audio', 'flash', 'object']

allowedFileExtensions

array the list of allowed file extensions for upload. This by default is set to null which means the plugin supports all file extensions for upload. If an invalid file extension is found, then a validation error message as set in msgInvalidFileExtension will be raised. An example of setting this could be:

['jpg', 'gif', 'png', 'txt']

Note

You need to be careful in case you are setting both allowedFileTypes and allowedFileExtensions. In this case, the allowedFileTypes property is validated first and generally precedes the allowedFileExtensions setting (and the latter validation maybe skipped).

allowedPreviewTypes

array the list of allowed preview types for your widget. This by default supports all file types for preview. The plugin by default treats each file as an object if it does not match any of the previous types. To disable this behavior, you can remove object from the list of allowedPreviewTypes OR fine tune it through allowedPreviewMimeTypes.To disable content preview for all file-types and show the previewIcon instead as a thumbnail, set this to null, empty, or false.

This is by default setup as following:

['image', 'html', 'text', 'video', 'audio', 'flash', 'object']

allowedPreviewMimeTypes

array the list of allowed mime types for preview. This is set to null by default which means all possible mime types are allowed. This setting works in combination with allowedPreviewTypes to filter only the needed file types allowed for preview. You can check this list of allowed mime types to add to this list if needed.

defaultPreviewContent

string, the default content / markup to show by default in the preview window whenever the files are cleared or the input is cleared. This can be useful for use cases like showing the default user profile picture or profile image before upload to overwrite. This is a bit different from initialPreview in the sense, that the initialPreview content will always be displayed unless it is deleted or overwritten based on overwriteInitial. The defaultPreviewContent on the other hand will only be shown ONLY on initialization OR whenever you clear the preview. At other times when files have been selected this will be overwritten temporarily until file(s) selected is/are cleared.

This property can be useful to display for example a default user profile picture (or saved picture) in the preview window unless the user selects a picture. Check the avatar upload demo example for details

customLayoutTags

object the list of additional custom tags that will be replaced in the layout templates. This should be an associative array object of key: value pairs, where:

  • key: string, is the tag to be replaced and as a standard is recommended to be enclosed between braces.

  • value: string|function, is the value that will replace the tag key above. This can be setup either as a string or callback function.

// example 1 - tags with value set as string
customLayoutTags: {
    '{tagA}': '<span class="badge badge-default">Tag A</span>',
    '{tagB}': 'Tag B',
}

// example 2 - tags with value set as callback
customLayoutTags: {
    '{tagC}': function() {
        return $("#element-id").val();
    }
}

customPreviewTags

object the list of additional custom tags that will be replaced in the preview templates. This should be an associative array object of key: value pairs, where:

  • key: string, is the tag to be replaced and as a standard is recommended to be enclosed between braces.

  • value: string|function, is the value that will replace the tag key above. This can be setup either as a string or callback function.

// example 1 - tags with value set as string
customPreviewTags: {
    '{tagA}': '<span class="badge badge-default">Tag A</span>',
    '{tagB}': 'Tag B',
}

// example 2 - tags with value set as callback
customPreviewTags: {
    '{tagC}': function() {
        return $("#element-id").val();
    }
}

fileTypeSettings

object the settings to validate and identify each file type when a file is selected for upload. This is a list of callbacks, which accepts the file mime type and file name as a parameter. This is by default setup as following:

// vType: is the file mime type
// vName: is the file name
{
    image: function(vType, vName) {
        return (typeof vType !== "undefined") ? vType.match('image.*') && !vType.match(/(tiff?|wmf)$/i) : vName.match(/\.(gif|png|jpe?g)$/i);
    },
    html: function(vType, vName) {
        return (typeof vType !== "undefined") ? vType == 'text/html' : vName.match(/\.(htm|html)$/i);
    },
	office: function (vType, vName) {
		return vType.match(/(word|excel|powerpoint|office|iwork-pages|tiff?)$/i) ||
			vName.match(/\.(rtf|docx?|xlsx?|pptx?|pps|potx?|ods|odt|pages|ai|dxf|ttf|tiff?|wmf|e?ps)$/i);
	},
    text: function(vType, vName) {
        return typeof vType !== "undefined" && vType.match('text.*') || vName.match(/\.(txt|md|csv|nfo|php|ini)$/i);
    },
    video: function (vType, vName) {
        return typeof vType !== "undefined" && vType.match(/\.video\/(ogg|mp4|webm)$/i) || vName.match(/\.(og?|mp4|webm)$/i);
    },
    audio: function (vType, vName) {
        return typeof vType !== "undefined" && vType.match(/\.audio\/(ogg|mp3|wav)$/i) || vName.match(/\.(ogg|mp3|wav)$/i);
    },
    flash: function (vType, vName) {
        return typeof vType !== "undefined" && vType == 'application/x-shockwave-flash' || vName.match(/\.(swf)$/i);
    },
    object: function (vType, vName) {
        return true;
    },
    other: function (vType, vName) {
        return true;
    },
}

previewFileIcon

string, the icon to be shown in each preview file thumbnail when an unreadable file type for preview is detected. Defaults to <i class="glyphicon glyphicon-file"></i> &nbsp;.

previewFileIconClass

string, the CSS class to be applied to the preview file icon container. Defaults to file-other-icon.

previewFileIconSettings

object the preview icon markup settings for each file extension (type). You need to set this as key: value pairs, where the key corresponds to a file extension (e.g. doc, docx, xls etc.), and the value corresponds to the markup of the icon to be rendered. If this is not set OR a file extension is not set here, the preview will default to previewFileIcon. Note that displaying the icons instead of file content is controlled via allowedPreviewTypes and allowedPreviewMimeTypes.

You can setup previewFileIconSettings as shown below:

previewFileIconSettings: {
    'doc': '<i class="fa fa-file-word-o text-primary"></i>',
    'xls': '<i class="fa fa-file-excel-o text-success"></i>',
    'ppt': '<i class="fa fa-file-powerpoint-o text-danger"></i>',
    'jpg': '<i class="fa fa-file-photo-o text-warning"></i>',
    'pdf': '<i class="fa fa-file-pdf-o text-danger"></i>',
    'zip': '<i class="fa fa-file-archive-o text-muted"></i>',
}

previewFileExtSettings

object the extensions to be auto derived for each file extension (type). This is useful if you want to set the same icon for multiple file extension types. You need to set this as `key: value` pairs, where the key corresponds to a file extension as set in previewFileIconSettings (e.g. doc, docx, xls etc.). The value will be a function callback that accepts the following parameter:

  • ext, string, the file extension (without the . [dot]) of the file currently selected in the preview.

You can configure the callback to match the set of file extensions (via regex or similar) for each `key` and return a boolean output if the file extension matches.

For example, you can setup `previewFileExtSettings` as shown below:

previewFileExtSettings: {
    'doc': function(ext) {
        return ext.match(/(doc|docx)$/i);
    },
    'xls': function(ext) {
        return ext.match(/(xls|xlsx)$/i);
    },
    'ppt': function(ext) {
        return ext.match(/(ppt|pptx)$/i);
    }
}

buttonLabelClass

string, the CSS class for the each of the button labels for browse, remove, upload, and cancel. Defaults to hidden-xs, which automatically hides the button labels for small screen devices and renders as smaller iconic buttons to fit to the screen.

browseLabel

string, the label to display for the file picker/browse button. Defaults to Browse ….

browseIcon

string, the icon to display before the label for the file picker/browse button. Defaults to <i class="glyphicon glyphicon-folder-open"></i>&nbsp;.

browseClass

string, the CSS class for the file picker/browse button. Defaults to btn btn-primary.

removeLabel

string, the label to display for the file remove button. Defaults to Remove.

removeIcon

string, the icon to display before the label for the file picker/remove button. Defaults to <i class="glyphicon glyphicon-trash"></i> &nbsp;.

removeClass

string, the CSS class for the file remove button. Defaults to btn btn-secondary.

removeTitle

string, the title to display on hover for the file remove button. Defaults to Clear selected files.

uploadLabel

string, the label to display for the file upload button. Defaults to Upload.

uploadIcon

string, the icon to display before the label for the file upload button. Defaults to <i class="glyphicon glyphicon-upload"></i> &nbsp;.

uploadClass

string, the CSS class for the file upload button. Defaults to btn btn-secondary.

uploadTitle

string, the title to display on hover for the file remove button. Defaults to Upload selected files.

uploadUrl

string, the URL for the upload processing action (typically for ajax based processing). Defaults to null. If this is not set or null, then the upload button action will default to form submission. NOTE: This is MANDATORY if you want to use advanced features like drag & drop, append/remove files, selectively upload files via ajax etc. The plugin automatically send $_FILES data to the server with the input `name` attribute as the key if provided. If input name is not set, the key defaults to file-data.

uploadThumbUrl

string, the URL for the ajax upload processing action applicable when each individual file thumbnail is separately uploaded. Defaults to null. If this is not set, this will default to the uploadUrl setting. This property is useful for synchronous uploads when uploadAsync is set to false, and you want to set a different server action for batch upload via uploadUrl, but a different server action for single file thumbnail upload via uploadThumbUrl.

uploadAsync

boolean whether the batch upload of multiple files will be asynchronous/in parallel. Defaults to true.

uploadExtraData

object | function, the extra data that will be passed as data to the url/AJAX server call via POST. This property is only applicable for ajax uploads and when you have set a value for uploadUrl.

This can be setup either as an object (associative array of keys and values) or as a function callback. As an object, it can be set for example as:

  {id: 100, value: '100 Details'}

As a function callback, the uploadExtraData can be setup as shown below. Note that for uploading individual file via thumbnail, the callback can also receive the thumbnail previewId and index as parameters. These are described below:

  • previewId: the identifier for the preview file container (only available when uploading each thumbnail file)

  • index: the zero-based sequential index of the loaded file in the preview list (only available when uploading each thumbnail file)

// previewId and index is only available for individual file upload via the thumbnail
function (previewId, index) {
    var obj = {};
    $('.your-form-class').find('input').each(function() {
        var id = $(this).attr('id'), val = $(this).val();
        obj[id] = val;
    });
    return obj;
}

zoomModalHeight

int, the default height in px for the modal window displaying the zoomed preview content. Defaults to 480.

minImageHeight

int, the minimum allowed image height in px if you are uploading image files. Defaults to null which means no limit on image height.

maxImageHeight

int, the maximum allowed image height in px if you are uploading image files. Defaults to null which means no limit on image height. Note that if you set resizeImage property to true, then the entire image will be resized within this height (depending on resizePreference).

minImageWidth

int, the minimum allowed image width in px if you are uploading image files. Defaults to null which means no limit on image width.

maxImageWidth

int, the maximum allowed image width in px if you are uploading image files. Defaults to null which means no limit on image width. Note that if you set resizeImage property to true, then the entire image will be resized within this width (depending on resizePreference).

resizeImage

boolean, whether to add ability to resize uploaded images. Defaults to false. Note that resizing images requires HTML5 canvas support which is supported on most modern browsers. In addition, you must include Piexifjs plugin by hMatoba by including plugins/piexif.min.js in your application. It is required to be loaded before fileinput.min.js for restoring the exif data to the image files when using the image resize feature of the bootstrap-fileinput plugin.

resizePreference

string, preference to resize the image based on width or height. Defaults to width. This property is parsed only when resizeImage is true. If set to width, the maxImageWidth property is first tested and if image size is greater than this, then the image is resized to maxImageWidth. The image height is resized and adjusted in the same ratio as width. In case, the image width is already less than maxImageWidth then the maxImageHeight property is used to resize and width is adjusted in same ratio.

This will behave conversely, when resizePreference is set to height - the maxImageHeight will be first tested against image height and then the rest of steps will be similarly parsed with preference given to height instead of width as before. For example:

// Example for resizePreference = 'width'
// - will resize image width to 200 px if image width is > 200 px
// - will resize image height to 200 px if image width is < 200 px and
//   image height is > 200 px
// if none of the above image will be returned as is
$('#file-input').fileinput({
    resizeImage: true,
    maxImageWidth: 200,
    maxImageHeight: 200,
    resizePreference: 'width'
});

resizeImageQuality

float, the quality of the resized image. This must be a decimal number between 0.00 to 1.00. Defaults to 0.92.

resizeDefaultImageType

string, the default image mime type of the converted image after resize. Defaults to image/jpeg.

resizeIfSizeMoreThan

float, the file size in KB beyond which the resize will be performed. Defaults to 0. Only files beyond a size set here will be resized.

minFileSize

float, the minimum file size for upload in KB. The file size must exceed the value set here, else a validation error is thrown using the msgSizeTooSmall setting. Defaults to 0. If this is set to null, then the validation is skipped and no minimum value check will be performed.

maxFileSize

float, the maximum file size for upload in KB. If greater than this, a validation error is thrown using the msgSizeTooLarge setting. If set to 0, it means size allowed is unlimited. Defaults to 0.

maxFilePreviewSize

float, the maximum preview file size for upload in KB. Files beyond this size will have a default thumbnail without the preview content. If set to 0 or null, it means the preview size allowed is unlimited. This is to be set carefully for optimal browser memory performance when previewing large files. Defaults to 25600 (i.e. 25 MB).

minFileCount

int the minimum number of files allowed for each multiple upload. If set to 0, it means number of files are optional. Defaults to 0.

maxFileCount

int the maximum number of files allowed for each multiple upload. If set to 0, it means number of files allowed is unlimited. Defaults to 0.

validateInitialCount

boolean, whether to include initial preview file count (server uploaded files) in validating minFileCount and maxFileCount. Defaults to false.

msgNo

string, the message that will be displayed when ZERO files are found. Defaults to No.

msgCancelled

string, the message that will be displayed within the progress bar when file upload is aborted or cancelled. Defaults to:

Cancelled

msgPlaceholder

string, the placeholder text that will be displayed within the main file caption when no files are selected. Defaults to:

Select {files}...

where, the {files} token will be displayed with:

  • filePlural if the multiple attribute of the file input has been set to true, OR

  • fileSingle if the multiple attribute of the file input is not set.

msgZoomTitle

string, the title displayed (before the file name) on hover of the zoom button for zooming the file content in a modal window. This is currently applicable only for text file previews. Defaults to:

View details

msgZoomModalHeading

string, the heading of the modal dialog that displays the zoomed file content. This is currently applicable only for text file previews. Defaults to:

Detailed Preview

msgFileRequired

string, the message to be displayed before upload (for ajax) or form submit (for non-ajax) when no files have been selected and the required property has been set to true. Defaults to:

You must select a file to upload.

Check the required validation demos for more details on usage of rtl validation.

msgSizeTooSmall

string, the message to be displayed when the file size is less than or equal to the minimum size set in minFileSize. Defaults to:

File "{name}" ({size} KB) is too small and must be larger than {minSize} KB.

where:

  • {name}: will be replaced by the file name being uploaded
  • {size}: will be replaced by the uploaded file size
  • {minSize}: will be replaced by the minFileSize parameter.

msgSizeTooLarge

string, the message to be displayed when the file size exceeds maximum size set in maxFileSize. Defaults to:

File "{name}" ({size} KB) exceeds maximum allowed upload size of {maxSize} KB. Please retry your upload!

where:

  • {name}: will be replaced by the file name being uploaded
  • {size}: will be replaced by the uploaded file size
  • {maxSize}: will be replaced by the maxFileSize parameter.

msgFilesTooLess

string, message to be displayed when the file count is less than the minimum count as set in minFileCount. Defaults to:

You must select at least {n} {files} to upload. Please retry your upload!

where:

  • {n}: will be replaced by the allowed minimum files as set in minFileCount.
  • {files}: will be replaced with fileSingle or filePlural properties in locale file depending on the minFileCount.

msgFilesTooMany

string, the message to be displayed when the file count exceeds maximum count as set in maxFileCount. Defaults to:

Number of files selected for upload ({n}) exceeds maximum allowed limit of {m}. Please retry your upload!

where:

  • {n}: will be replaced by number of files selected for upload

  • {m}: will be replaced by the allowed maximum files as set in maxFileCount

msgFileNotFound

string, the exception message to be displayed when the file selected is not found by the FileReader. Defaults to:

File "{name}" not found!

where:

  • {name}: will be replaced by the file name being uploaded

msgFileSecured

string, the exception message to be displayed when the file selected is not allowed to be accessed due to a security exception. Defaults to:

Security restrictions prevent reading the file <code>"{name}"</code>.

where:

  • {name}: will be replaced by the file name being uploaded

msgFileNotReadable

string, the exception message to be displayed when the file selected is not readable by the FileReader API. Defaults to:

File "{name}" is not readable.

where:

  • {name}: will be replaced by the file name being uploaded

msgFilePreviewAborted

string, the exception message to be displayed when the file preview upload is aborted. Defaults to:

File preview aborted for "{name}".

where:

  • {name}: will be replaced by the file name being uploaded

msgFilePreviewError

string, the exception message to be displayed for any other error when previewing the file. Defaults to:

An error occurred while reading the file "{name}".

where:

  • {name}: will be replaced by the file name being uploaded

msgInvalidFileName

string, the message to be displayed when the slugified file name returns an empty string. Defaults to:

Invalid or unsupported characters in file name "{name}".

where:

  • {name}: will be replaced by the file name being uploaded

msgInvalidFileType

string, the message to be displayed when the file type is not in one of the file types set in allowedFileTypes. Defaults to:

Invalid type for file "{name}". Only "{types}" files are supported.

where:

  • {name}: will be replaced by the file name being uploaded
  • {types}: will be replaced by the comma separated list of types defined in allowedFileTypes.

msgInvalidFileExtension

string, the message to be displayed when the file type is not in one of the file extensions set in allowedFileExtensions. Defaults to:

Invalid extension for file "{name}". Only "{extensions}" files are supported.

where:

  • {name}: will be replaced by the file name being uploaded
  • {extensions}: will be replaced by the comma separated list of extensions defined in allowedFileExtensions.

msgUploadAborted

string, the message to be displayed when an ongoing ajax file upload is aborted by pressing the Cancel button. Defaults to:

The file upload was aborted

If this is set to null or empty, the internal ajax error message will be displayed. Defaults to:

File Upload Error

msgUploadThreshold

string, the message to be displayed within the progress bar when the progress exceeds the progressUploadThreshold setting. Defaults to:

Processing...

msgUploadBegin

string, the message to be displayed within the progress bar when the progress is 0% and upload is about to begin. Defaults to:

Initializing...

msgUploadEnd

string, the message to be displayed within the progress bar when the progress is 100% and upload is completed. Defaults to:

Done

msgUploadEmpty

string, the error message displayed when no files or extra data were found to upload or submit. Defaults to:

No valid data available for upload

msgUploadError

string, the message displayed within the upload progress bar when an ajax validation error is received from the server for the ajax upload. The message is applicable for both the main upload progress bar as well as each individual file thumbnail progress bar. Defaults to:

Error

msgValidationError

string, the exception message to be displayed within the caption container (instead of msgFilesSelected), when a validation error is encountered. Defaults to:

File Upload Error

msgValidationErrorClass

string, the css class for the validation error message displayed in the caption container. Defaults to text-danger.

msgValidationErrorIcon

string, the icon to be displayed before the validation error in the caption container. Defaults to <i class="fa fa-exclamation-circle"></i>

msgErrorClass

string, the css class for the error message to be displayed in the preview window when the file size exceeds maxSize. Defaults to file-error-message.

msgLoading

string, the message displayed when the files are getting read and loaded for preview. Defaults to

Loading file {index} of {files} …

The following special variables will be replaced:

  • {index}: the sequence number of the current file being loaded.
  • {files}: the total number of files selected for upload.

msgProgress

string, the progress message displayed as each file is loaded for preview. Defaults to:

Loading file {index} of {files} - {name} - {percent}% completed.

The following variables will be replaced:

  • {index}: the sequence number of the current file being loaded.
  • {files}: the total number of files selected for upload.
  • {percent}: the percentage of file read and loaded.
  • {name}: the name of the current file being loaded.

msgSelected

string, the progress message displayed in caption window when multiple (more than one) files are selected. Defaults to:

{n} files selected

where:

  • {n}: will be replaced with the number of files selected.

msgFoldersNotAllowed

string, the message displayed when a folder has been dragged to the drop zone. Defaults to:

Drag & drop files only! {n} folder(s) dropped were skipped.

where:

  • {n}: will be replaced with the number of folders dropped.

msgImageWidthSmall

string, the exception message to be displayed when the file selected for preview is an image and its width is less than the minImageWidth setting. Defaults to:

Width of image file "{name}" must be at least {size} px.

where:

  • {name}: will be replaced by the file name being uploaded.

  • {size}: will be replaced by the minImageWidth setting.

msgImageHeightSmall

string, the exception message to be displayed when the file selected for preview is an image and its height is less than the minImageHeight setting. Defaults to:

Height of image file "{name}" must be at least {size} px.

where:

  • {name}: will be replaced by the file name being uploaded.

  • {size}: will be replaced by the minImageHeight setting.

msgImageWidthLarge

string, the exception message to be displayed when the file selected for preview is an image and its width exceeds the maxImageWidth setting. Defaults to:

Width of image file "{name}" cannot exceed {size} px.

where:

  • {name}: will be replaced by the file name being uploaded.

  • {size}: will be replaced by the maxImageWidth setting.

msgImageHeightLarge

string, the exception message to be displayed when the file selected for preview is an image and its height exceeds the maxImageHeight setting. Defaults to:

Height of image file "{name}" cannot exceed {size} px.

where:

  • {name}: will be replaced by the file name being uploaded.

  • {size}: will be replaced by the maxImageHeight setting.

msgImageResizeError

string, the message to be displayed when an error is received during image resize operation. Defaults to:

Could not get the image dimensions to resize.

msgImageResizeException

string, the message to be displayed when an exception is thrown during image resize operation. Defaults to:

Error while resizing the image.<pre>{errors}</pre>.

where:

  • {errors}: will be replaced by the javascript exception message.

msgAjaxError

string, the message to be displayed when an unknown error or exception is received during any of the ajax operations (e.g. upload or delete). Defaults to:

Something went wrong with the {operation} operation. Please try again later!

where:

  • {operation}: will be replaced by the file operation (see ajaxOperations for list of ajax operations supported by the plugin)

msgAjaxProgressError

string, the message to be displayed in the progress bar when an unknown error or exception is received during any of the ajax operations (e.g. upload or delete). Defaults to:

{operation} failed

where:

  • {operation}: will be replaced by the file operation (see ajaxOperations for list of ajax operations supported by the plugin)

ajaxOperations

object, the user friendly messages displayed for each of the ajax operations (and used in msgAjaxError to display an error specific to an ajax operation. The keys must be one of deleteThumb, uploadThumb, uploadBatch, or , uploadExtra. Defaults to:

{
    deleteThumb: 'file delete',
    uploadThumb: 'file upload',
    uploadBatch: 'batch file upload',
    uploadExtra: 'form data upload'
}

progressClass

string, the upload progress bar CSS class to be applied when AJAX upload is in process (applicable only for ajax uploads). Defaults to progress-bar progress-bar-success progress-bar-striped active.

progressCompleteClass

stringthe upload progress bar CSS class to be applied when AJAX upload is complete. Defaults to progress-bar progress-bar-success.

progressErrorClass

stringthe upload progress bar CSS class to be applied when AJAX upload is cancelled or aborted. Defaults to progress-bar progress-bar-danger.

progressUploadThreshold

int the percentage progress threshold until which the file upload progress indicator will display the percentage. Defaults to 99, beyond which the progress bar will display the msgUploadThreshold.

previewFileType

string, the type of files that are to be displayed in the preview window. Defaults to image. Can be one of the following:

  • image: Only image type files will be shown in preview.
  • text: Only text type files will be shown in preview.
  • any: Both image and text files content will be shown in preview.

Files other than image or text will be displayed as a thumbnail with the filename in the preview window.

zoomIndicator

string, the icon for zooming the file content in a new modal dialog. This is currently applicable only for text file previews. Defaults to <i class="glyphicon glyphicon-zoom-in"></i>

elErrorContainer

string, the identifier for the container element displaying the error (e.g. '#id'). If not set, will default to the container with CSS class kv-fileinput-error inside the preview container (identified by elPreviewContainer). The CSS class as set in msgErrorClass will be automatically appended to this container element when displaying the error markup.

elCaptionContainer

string, the identifier for the container element containing the caption (e.g. '#id'). If not set, will default to the container with CSS class file-caption inside the main plugin container.

elCaptionText

string, the identifier for the container element containing the caption text (e.g. '#id'). If not set, will default to the container with CSS class file-caption-name inside the main plugin container.

elPreviewContainer

string, the identifier for the container element containing the preview (e.g. '#id'). If not set, will default to the container with CSS class file-preview inside the main plugin container.

elPreviewImage

string, the identifier for the element containing the preview image thumbnails (e.g. '#id'). If not set, will default to the container with CSS class file-preview-thumbnails inside the main plugin container.

elPreviewStatus

string, the identifier for the element containing the preview progress status (e.g. '#id'). If not set, will default to the container with CSS class file-preview-status inside the main plugin container.

slugCallback

function a callback to convert the filename as a slug string eliminating special characters. If not set, it will use the plugin's own internal slugDefault method. This callback function includes the filename as parameter and must return a converted filename string. This defaults to the following callback:

slugCallback: function (text) {
    return isEmpty(text) ? '' : String(text).replace(/[\[\]\/\{}:;#%=\(\)\*\+\?\\\^\$\|<>&"']/g, '_');
}

One can override this to what they want for their use case. For example:

slugCallback: function(filename) {
    return filename.replace('(', '_');
}

dropZoneEnabled

boolean whether to enable a drag and drop zone for dragging and dropping files to. This is available only for ajax based uploads. Defaults to true.

dropZoneTitle

string, title to be displayed in the drag and drop zone. This is available only for ajax based uploads. Defaults to:

Drag & drop files here …

dropZoneTitleClass

string, CSS class for the drag & drop zone title. Defaults to file-drop-zone-title.

dropZoneClickTitle

string, title to be appended to the dropZoneTitle in the drag and drop zone when browseOnZoneClick is true. This is available only for ajax based uploads. Defaults to <br>(or click to select {files}).

fileActionSettings

object configuration for setting up file actions for newly selected file thumbnails in the preview window. The following properties can be set: The following properties can be set:

  • showUpload: boolean, whether to show the upload button in the thumbnail

  • showDownload: boolean, whether to show the download button in the thumbnail

  • showRemove: boolean, whether to show the remove button in the thumbnail

  • showZoom: boolean, whether to show the zoom button in the thumbnail

  • showDrag: boolean, whether to show the drag button in the thumbnail (applicable only for initial preview content)

  • uploadIcon: string, icon for upload button to be displayed in each file thumbnail.

  • uploadClass: string, CSS class for the upload button in each file thumbnail.

  • uploadTitle: string, title for upload button in each file thumbnail.

  • uploadRetryIcon: string, icon to be displayed for upload button after an upload error is encountered from the server to allow retry of the upload. This will be rendered in such a case for the errored file thumbnail when retryErrorUploads is set to true.

  • uploadRetryIcon: string, title to be displayed for upload button after an upload error is encountered from the server to allow retry of the upload. This will be rendered in such a case for the errored file thumbnail when retryErrorUploads is set to true.

  • downloadIcon: string, icon for download button to be displayed in each file thumbnail.

  • downloadClass: string, CSS class for the download button in each file thumbnail.

  • downloadTitle: string, title for download button in each file thumbnail.

  • removeIcon: string, icon for remove button to be displayed in each file thumbnail.

  • removeClass: string, CSS class for the remove button in each file thumbnail.

  • removeTitle: string, title for remove button in each file thumbnail.

  • zoomIcon: string, icon for zoom button to be displayed in each file thumbnail (to zoom thumbnail content to a detailed modal preview).

  • zoomClass: string, CSS class for the zoom button in each file thumbnail (to zoom thumbnail content to a detailed modal preview).

  • zoomTitle: string, title for zoom button in each file thumbnail (to zoom thumbnail content to a detailed modal preview).

  • dragIcon: string, icon for drag button to be displayed in each file thumbnail (to sort / rearrange items in initial preview).

  • dragClass: string, CSS class for the drag button in each file thumbnail (to sort / rearrange items in initial preview).

  • dragTitle: string, title for drag button in each file thumbnail (to sort / rearrange items in initial preview).

  • dragSettings: object, the configuration for the Sortable plugin that will allow you to control the drag settings.

  • indicatorNew: string, an indicator (HTML markup) for new pending upload displayed in each file thumbnail.

  • indicatorSuccess: string, an indicator (HTML markup) for successful upload displayed in each file thumbnail.

  • indicatorError: string, an indicator (HTML markup) for error in upload displayed in each file thumbnail.

  • indicatorLoading: string, an indicator (HTML markup) for ongoing upload displayed in each file thumbnail.

  • indicatorNewTitle: string, title to display on hover of indicator for new pending upload in each file thumbnail.

  • indicatorSuccessTitle: string, title to display on hover of indicator for successful in each file thumbnail.

  • indicatorErrorTitle: string, title to display on hover of indicator for error in upload in each file thumbnail.

  • indicatorLoadingTitle: string, title to display on hover of indicator for ongoing upload in each file thumbnail.

Defaults to the following setting:

{
    showRemove: true,
    showUpload: true,
    showDownload: true,
    showZoom: true,
    showDrag: true,
    removeIcon: '<i class="glyphicon glyphicon-trash"></i>',
    removeClass: 'btn btn-kv btn-default btn-outline-secondary',
    removeErrorClass: 'btn btn-kv btn-danger',
    removeTitle: 'Remove file',
    uploadIcon: '<i class="glyphicon glyphicon-upload"></i>',
    uploadClass: 'btn btn-kv btn-default btn-outline-secondary',
    uploadTitle: 'Upload file',
    uploadRetryIcon: '<i class="glyphicon glyphicon-repeat"></i>',
    uploadRetryTitle: 'Retry upload',
    downloadIcon: '<i class="glyphicon glyphicon-download"></i>',
    downloadClass: 'btn btn-kv btn-default btn-outline-secondary',
    downloadTitle: 'Download file',
    zoomIcon: '<i class="glyphicon glyphicon-zoom-in"></i>',
    zoomClass: 'btn btn-kv btn-default btn-outline-secondary',
    zoomTitle: 'View Details',
    dragIcon: '<i class="glyphicon glyphicon-move"></i>',
    dragClass: 'text-info',
    dragTitle: 'Move / Rearrange',
    dragSettings: {},
    indicatorNew: '<i class="glyphicon glyphicon-plus-sign text-warning"></i>',
    indicatorSuccess: '<i class="glyphicon glyphicon-ok-sign text-success"></i>',
    indicatorError: '<i class="glyphicon glyphicon-exclamation-sign text-danger"></i>',
    indicatorLoading: '<i class="glyphicon glyphicon-hourglass text-muted"></i>',
    indicatorNewTitle: 'Not uploaded yet',
    indicatorSuccessTitle: 'Uploaded',
    indicatorErrorTitle: 'Upload Error',
    indicatorLoadingTitle: 'Uploading ...'
}

otherActionButtons

string, markup for additional action buttons to display within the initial preview thumbnails (for example displaying an image edit button). The following tags can be used in the markup and will be automatically replaced:

  • {key}: Will be replaced with the key property set for each preview thumbnail setting within initialPreviewConfig.

  • {dataKey}: Will be replaced with data-key="{keyval}", where {keyval} is the key property set for each preview thumbnail setting within initialPreviewConfig.

  • {dataUrl}: Will be replaced with data-url="{urlval}", where {urlval} is the delete url property set for each preview thumbnail setting within initialPreviewConfig.

  • {downloadUrl}: the url to be used to trigger the download of the selected thumbnail. This will be derived from the downloadUrl property for the thumbnail frame within initialPreviewConfig or if this is not set, will be auto derived from the initialPreviewDownloadUrl setting. If neither are set, or the url is set to false, then the download action button will not be displayed.

  • {caption}: the name of the file that will be downloaded. Will be derived from the filename property for the thumbnail frame within initialPreviewConfig or if that is not available, will use the caption property for the thumbnail frame within initialPreviewConfig.

    NOTE The caption name to download the file will be displayed using the HTML5 download attribute for the download link tag. The feature is supported only on specific browsers. Also the link to download the files must be on the same domain to prevent cross origin resource sharing (CORS) issue.

For example, you can set a custom button (or chain/append multiple button markups) like below:

var btns = '<button type="button" class="kv-cust-btn btn btn-kv btn-secondary" title="Edit"{dataKey}>' +
    '<i class="glyphicon glyphicon-edit"></i>' +
    '</button>';
// note the tag/token {dataKey} 
$('#input-id').fileinput({
    otherActionButtons: btns,
    // configure other plugin settings
});

You can write a custom action on the button by parsing the CSS class and/or the data key. For example:

$('.kv-cust-btn').on('click', function() {
    var $btn = $(this), key = $btn.data('key');
    // do some actions based on the key
}); 

textEncoding

string, the encoding to be used while reading a text file. Applicable only for previewing text files. Defaults to UTF-8.

ajaxSettings

object additional ajax settings to pass to the plugin before submitting the ajax request for upload. Applicable only for ajax uploads. This can be useful to pass additional tokens to headers or one can use it for setting other ajax options for advanced cases. Refer the jQuery ajax documentation for the various settings you can configure.

ajaxDeleteSettings

object additional ajax settings to pass to the plugin before submitting the delete ajax request in each initial preview thumbnail. Applicable only for ajax deletions. This can be useful to pass additional tokens to headers or one can use it for setting other ajax options for advanced cases. Refer the jQuery ajax documentation for the various settings you can configure.

showAjaxErrorDetails

boolean, whether to show details of the error stack from the server log when an error is encountered via ajax response. Defaults to true.

mergeAjaxCallbacks

boolean|string, whether to merge the ajax callback functions set in ajaxSettings with the default plugin callbacks for beforeSend, success, error, complete. Defaults to false.

In addition to boolean false, the following string values can be set:

  • 'before': when set to 'before', the ajax callbacks set in ajaxSettings will be merged before the default plugin callback.

  • 'after': when set to 'after', the ajax callbacks set in ajaxSettings will be merged after the default plugin callback.

mergeAjaxDeleteCallbacks

boolean|string, whether to merge the ajax callback functions set in ajaxDeleteSettings with the default plugin callbacks for beforeSend, success, error, complete. Defaults to false.

In addition to boolean false, the following string values can be set:

  • 'before': when set to 'before', the ajax callbacks set in ajaxDeleteSettings will be merged before the default plugin callback.

  • 'after': when set to 'after', the ajax callbacks set in ajaxDeleteSettings will be merged after the default plugin callback.

retryErrorUploads

boolean, whether to allow retry of file upload for file thumbnails that have errored out due to a server generated validation error via the ajax response. Defaults to true.

Note

You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.

The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.