kartik-v/bootstrap-fileinput: a jQuery file picker for Bootstrap 3, 4 and 5

The gap bootstrap-fileinput fills between a raw input and a full upload service

A bare <input type="file"> gives you a button, a filename and nothing else. No thumbnail, no progress bar, no way to remove one file from a selection of ten, and no way to send the bytes without a full page reload. Building that layer by hand means writing FileReader preview code, a drag-and-drop drop zone, an XHR progress handler and per-file delete state. bootstrap-fileinput packages those pieces as a jQuery plugin that dresses itself in Bootstrap CSS.

The target user is specific. You are maintaining a server-rendered application, probably PHP, Rails or a Django admin, where Bootstrap and jQuery are already on the page and the upload form is one field among many. The README describes previews for images, text, HTML, video, audio, flash and objects, plus AJAX uploads, drag and drop and selective add or delete. That is a form-control replacement, not an application framework. If your front end is a React or Vue component tree, the jQuery dependency makes this the wrong tool before you write a line of code.

How the plugin detects your Bootstrap version and what changed in 5.x

The plugin ships one JavaScript file, js/fileinput.js, and one stylesheet, css/fileinput.css, per package.json. Bootstrap support spans 3.x, 4.x and 5.x. Since v5.2.0 the plugin can detect the Bootstrap library version automatically when the Bootstrap JS file is loaded, and the README points to $.fn.fileinputBsVersion as the override for cases where detection misfires. That override exists because detection is heuristic; if you load Bootstrap through a bundler under a different global, set the version explicitly rather than debugging a half-styled widget.

Version 5.x is described in the README as a significant rewrite with enhanced file management and resumable chunk uploads. The repository topics list chunk, chunked-uploads and resumable-upload, so chunking is a first-class concern rather than an add-on. Uploads go out over XHR2 with FormData, which the README lists as the requirement for AJAX mode. Browsers without FormData or XHR2 fall back to normal form submission, so the control degrades to a plain file field instead of breaking.

Two themes ship with it. The default Krajee theme and the Krajee Explorer theme, available since v4.3.7, which presents files as a table-like list. Theming is CSS, not a component API, which is why the repository carries a scss/ directory and a separate sass branch for bootstrap-sass installs.

Installing bootstrap-fileinput and wiring a first upload form

The README lists four install paths. Pick the one matching your build. For a Node build, npm install bootstrap-fileinput. For older Bower projects, bower install bootstrap-fileinput. For PHP projects, Composer with the @dev constraint. For no build system at all, download the ZIP or TAR ball and copy the css and js folders into your project.

npm install bootstrap-fileinput

Loading order matters. The README says to load Bootstrap CSS, then an icon library, then the plugin stylesheet, then jQuery, then the plugin JS. The default icons come from the Bootstrap Icons library; the README also documents Font Awesome as an alternative when using the fas theme or Bootstrap 4.x.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.min.css" crossorigin="anonymous">
<link href="https://cdn.jsdelivr.net/gh/kartik-v/[email protected]/css/fileinput.min.css" media="all" rel="stylesheet" type="text/css" />

With the assets in place, initialize the plugin on a file input. The examples directory in the repository contains index-bs3.html, index-bs4.html and index-bs5.html, so you can open the file matching your Bootstrap version and compare markup directly. Expect a styled picker with a browse button and, once a file is chosen, a preview thumbnail with a remove control.

One caveat before you copy the examples: the README does not document the exact JSON response shape the server must return for the upload URL, so read the examples pages or the plugin documentation site before assuming a format.

jQuery, IE10 and the fallback behaviour you inherit

The prerequisites are explicit: Bootstrap 5.x, 4.x or 3.x, the latest jQuery, and a modern browser with HTML5 input and FileReader support. For Internet Explorer, IE10 and above are required. IE9 and below still render, but they behave as a normal file input with no multiple selection and no FileReader preview. AJAX uploads require FormData and XHR2, and the plugin degrades to form submission without them.

That degradation is honest but it also means your server must handle two submission paths if you support old browsers: the XHR path and the plain multipart form post. Teams often wire only the AJAX handler and discover the fallback later. If your audience is entirely on evergreen browsers, you can ignore this. If not, budget for the second path.

package.json declares jquery >= 1.9.0 and bootstrap >= 3.4.1 as dependencies, with jquery >= 1.9.0 and bootstrap >= 3.0.0 as peer dependencies. The mismatch between those two ranges is worth noticing: the peer range is looser than the dependency range. If your project pins Bootstrap 3.0 through 3.4.0, the peer declaration will not complain but the dependency range suggests the plugin expects 3.4.1 or later. Treat the stricter number as the real floor.

Where bootstrap-fileinput stops being the right answer

The hard boundary is the jQuery dependency. In a component-based front end, mounting a jQuery plugin means managing a DOM node outside your framework's render cycle, re-initializing on every route change and reconciling state by hand. That cost is real and the plugin offers nothing to reduce it.

A second boundary is scope. This is a client-side control. It does not store files, generate thumbnails server-side, scan uploads or manage retention. The AJAX mode sends bytes to an endpoint you write and own. If you need upload infrastructure rather than an upload widget, this project is the wrong layer.

A third is release cadence. The last push to master was on 2026-05-12, and the most recent tagged release listed is v5.5.4 from 2024-04-09, with v5.5.3 in March 2024 and v5.5.2 back in October 2022. package.json carries version 5.5.5, which is ahead of the newest tag in the release list; that is a normal pattern when a version bump lands before tagging, but it means the npm version and the tagged release may not be the same commit. Check which one you are pinning.

bootstrap-fileinput compared with Dropzone

Dropzone is the comparison people reach for, and the difference is architectural rather than cosmetic. Dropzone is built around a drop zone as the primary interface: you designate an element, it owns the upload lifecycle, and the file list is the UI. bootstrap-fileinput starts from the file input element and enhances it in place, so it slots into an existing form field without restructuring the surrounding markup.

That matters when the upload is one field among many in a form you submit as a whole. With bootstrap-fileinput the control behaves like a form input you can validate and lay out alongside text fields. With Dropzone you are more likely to build the form around the uploader. Both send XHR uploads; bootstrap-fileinput's distinguishing feature set in this repository is the preview breadth (images, text, HTML, video, audio, flash, objects) and the resumable chunk upload support added in the 5.x rewrite.

The other alternative is writing it yourself against the FileReader and XHR2 APIs. That is a few hundred lines for previews, progress and delete handling, and it removes the jQuery dependency entirely. For a single simple image field, that is often the better trade.

Licence, packaging and what an upgrade actually costs

The repository's LICENSE.md is the licence file, and package.json declares BSD-3-Clause, while the GitHub API reports the licence as NOASSERTION. That discrepancy is worth resolving with your own reading of LICENSE.md before you rely on a specific licence identifier in a compliance record. This is not legal advice; the point is that the machine-readable field and the package manifest disagree, and only the file itself settles it.

The package is published to several ecosystems at once: npm, Bower, Composer via Packagist, and a nuget/ directory in the repository root. That breadth is convenient and also means versions can drift between registries. Pin one source.

Upgrade cost is concentrated in the 4.x to 5.x step, which the README calls a significant rewrite. Within 5.x, the Bootstrap 5 support arrived in v5.2.0 with automatic version detection, so moving from Bootstrap 4 to 5 on a 5.2+ plugin version is mostly a CSS and markup concern. The postinstall script runs opencollective-postinstall with a || true guard, so a failed postinstall will not break your build. If your CI blocks network access during install, that guard is what keeps the install green.

Editorial conclusion

Adopt it if your pages are server-rendered Bootstrap templates with jQuery already loaded and you want previews, multi-select and chunked AJAX uploads without writing that layer yourself. Skip it if you are building a React, Vue or Angular front end with no jQuery, or if you need a maintained upload component with an active release cadence, since the last push to master was on 2026-05-12 and the last tagged release was v5.5.4 on 2024-04-09. Before committing, verify three things in a browser: that the plugin detects your Bootstrap version, that a real chunked upload resumes after an interrupted connection, and that your server returns the JSON response shape the uploadUrl handler expects.

Frequently asked questions

Official sources

1. Issues
2. kartik-v/bootstrap-fileinput on GitHub
3. Project website
4. README
5. Releases