# baguetteBox.js is a 3.2KB lightbox with an install hook nobody declared and a Composer recipe pointing at the wrong branch

> A dependency-free JavaScript lightbox whose feature list is small but whose packaging carries several decisions worth reading first: a postinstall rebuild of a native module absent from its own manifest, two incompatible override spellings, six installation routes, CDN steps numbered out of order, and a responsive image feature that is named but never specified.

**feimosi/baguetteBox.js** — :zap: Simple and easy to use lightbox script written in pure JavaScript

- Repository: https://github.com/feimosi/baguetteBox.js
- Website: https://feimosi.github.io/baguetteBox.js/
- Stars: 2,503 · Forks: 426
- Language: JavaScript
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/feimosi-baguettebox-js

## The default branch is dev, and the Composer recipe asks for dev-main

The branch the repository opens by default is dev, and the Composer instructions in the same document ask for a version constraint of dev-main inside composer.json. Those two names cannot both resolve, so the one installation route that reaches the repository through a version control reference points at a branch the project does not use as its default. The naming differences run through every entry point: the npm package is baguettebox.js in lowercase, the Composer package is feimosi/baguettebox.js, the repository itself is spelled baguetteBox.js with a capital B, and the demo page and badges keep that camel case. Import styles follow the same split, with a require call, an ES2015 import, and a global name baguetteBox exposed when the file is loaded through a script tag with no explicit import.

## Three releases in six years, and the newest tag sits four months before the last push

Three releases are named. v1.11.1 is dated 2020-03-31, v1.12.0 is dated 2024-07-14, and v1.13.0 is dated 2025-11-09, a gap of more than four years between the first two and about sixteen months between the last two. The manifest version agrees with the newest tag exactly, at 1.13.0, so the published package and the latest release point do not disagree. What sits beside them is the branch: the most recent push to dev is dated 2026-03-09, four months after the v1.13.0 tag. Anything committed to the branch after that date sits outside every published version, which means the gap between the release list and the branch head is a real gap rather than a naming artifact.

## Every install rebuilds node-sass, a package the manifest never declares

The install lifecycle is not empty. A postinstall script runs npm rebuild node-sass, so every consumer pays a native rebuild step at install time. The declared build tooling does not include node-sass anywhere: the stylesheet dependencies are gulp-sass at ~5.1.0 and sass at ~1.77.8. Two override mechanisms also sit side by side in the same manifest, a resolutions entry pinning natives to 1.1.3, which is the Yarn spelling, and an overrides entry pinning graceful-fs and gift, which is the npm spelling. An .npmrc file sits at the top level next to a .travis.yml, so the repository carries configuration for more than one resolution path while any single consumer runs one of them.

## Six installation routes for a script the size of a small stylesheet

The feature list puts the gzipped size at around 3.2KB, with SVG buttons and no extra files to download, and the installation section offers six ways to reach it. npm is the plainest:

```sh
npm install baguettebox.js --save
```

Yarn is yarn add baguettebox.js, Bower is bower install baguettebox.js --save, and a bower.json sits at the top level to match Bower. Two routes bypass package managers: a CDN pair from cdnjs or jsdelivr, and a manual download of baguetteBox.min.css and baguetteBox.min.js from the dist folder. The sixth is Composer, the awkward one for a browser script. What lands in the package is set by the files array, which names dist and src, and the main field points at dist/baguetteBox.min.js with style pointing at the matching minified stylesheet, so the entry point every consumer loads is the built artifact.

## The CDN instructions are numbered 1, then 3, then 2

The CDN subsection steps out of order. It opens by naming a provider, jumps ahead to copying the URLs of the latest version for both the .js and .css files, and only then arrives at pasting those URLs into a document, so the sequence reads as 1, 3, 2. The snippet it points at is a stylesheet link followed by a script tag marked async:

```html
<link rel="stylesheet" href="<CSS URL>">
<script src="<JS URL>" async></script>
```

That async attribute sits awkwardly beside a separate warning in the usage section, which says that when the file is included with a script tag, initialization has to wait for the document to load, with the example wrapping baguetteBox.run('.gallery') in a window load listener. A script that may arrive at an unpredictable time plus a call that must not run early leaves ordering as the consumer's problem.

## The options table, not the feature list, is the actual contract

The eleven bullets in the feature list describe intentions. The seventeen row options table describes behavior, and several rows carry decisions a feature summary would hide. The captions option defaults to true and accepts a function that receives the a element containing the image and is invoked in the context of the current gallery array, so a caption can be computed per link. The buttons option defaults to 'auto', which hides the controls on touch enabled devices and when only one image is available. The filter option is a regular expression applied to the href attribute, defaulting to /.+\.(gif|jpe?g|png|webp)/i, so a link pointing outside that extension list is not treated as an image. Preloading defaults to two files, animation defaults to slideIn and also accepts fadeIn or false, and the overlay background defaults to rgba(0,0,0,0.8).

## run returns an array, so show needs a gallery pulled out of it

The documented surface is five functions, and the return values carry the argument shapes. run(selector, userOptions) takes a string handed to querySelectorAll and returns an array of gallery objects reflecting the elements the selector found, which is why the usage example indexes into that result before opening anything:

```js
const gallery = baguetteBox.run('.gallery');
baguetteBox.show(index, gallery[0]);
```

show(index, gallery) returns a boolean, true on success and false when the index is invalid, and it assumes the currently opened gallery when the gallery argument is omitted. showNext and showPrevious also return booleans, false when there are no more images to load. hide closes the gallery, and destroy removes the plugin along with any event bindings, the only cleanup entry point in the documented API.

## Responsive images stop one clause after the attribute name

The responsive image feature is introduced by placing data-at-{width} attributes on the a tags, with the value being the path to the desired image, and the sentence that goes on to say what {width} should be stops there. No breakpoint list, no ordering rule and no sample markup accompany it, so the feature is named without being specified. Two other boundaries sit close by. The table of contents promises a compatibility section, and the only browser floor stated anywhere in the options is the note that bodyClass works in IE 10 and later. The accessibility bullet resolves into the same few hooks: a class appended to the body element while the lightbox is visible, defaulting to baguetteBox-open, the titleTag option that copies a caption into the img title attribute, and captions shown by default. Nothing in the documented API describes keyboard navigation, focus handling or ARIA attributes.

## Conclusion

baguetteBox.js suits a static site that needs a gallery overlay and nothing else: no dependencies, a documented option surface, and an API small enough to read in one sitting. The cost of that smallness sits in the packaging rather than in the code, and it is worth reading before installing: an install hook that rebuilds a native module the manifest never declares, two override spellings in one file, a Composer recipe pointing at a branch the repository does not use, and CDN steps numbered out of order. Two dates are worth weighing. The newest release is v1.13.0 from 2025-11-09 and the most recent push to the default branch dev is dated 2026-03-09, so check that a toolchain pinned to gulp 3.9.1 and an install hook that rebuilds node-sass still runs on the Node version you intend to use, and decide whether a body class hook is enough accessibility for the pages you intend to ship.

## FAQ

### How do I install baguetteBox.js and open a gallery?

Run npm install baguettebox.js --save, or add the two files from the dist folder, then call baguetteBox.run('.gallery') with a selector for a container holding a tags. If you load the file with a script tag rather than an import, the call has to wait for the document load event.

### What does baguetteBox.run return in baguetteBox.js?

It returns an array of gallery objects reflecting the elements the selector matched, which is why passing a single gallery to show means indexing the result, as in baguetteBox.show(index, gallery[0]). show returns a boolean that is false when the index is invalid.

### Does baguetteBox.js need jQuery or any other dependency?

No. It is written in pure JavaScript with no dependencies required, and it can be loaded as a global through a script tag, pulled in with require, or imported as an ES2015 module.

### How current is baguetteBox.js?

The newest release is v1.13.0 from 2025-11-09 and the most recent push to the default branch dev is dated 2026-03-09, while the previous tags are v1.12.0 from 2024-07-14 and v1.11.1 from 2020-03-31. The manifest version matches the newest tag exactly.

## Sources

- [feimosi/baguetteBox.js on GitHub](https://github.com/feimosi/baguetteBox.js)
- [License: MIT](https://github.com/feimosi/baguetteBox.js/blob/dev/LICENSE)
- [Project website](https://feimosi.github.io/baguetteBox.js/)
- [README](https://github.com/feimosi/baguetteBox.js/blob/dev/README.md)
- [Releases](https://github.com/feimosi/baguetteBox.js/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/feimosi-baguettebox-js