# ngx-gallery has moved its docs to Storybook and its release to next tags

> ngx-gallery is an Angular gallery, carousel and lightbox library published as ng-gallery on npm, now documented through a Storybook hub with older Angular versions kept on an archived site and a wiki. The current line ships only as v13.0.0 next tags.

**MurhafSousli/ngx-gallery** — Angular Gallery, Carousel and Lightbox

- Repository: https://github.com/MurhafSousli/ngx-gallery
- Website: https://murhafsousli.github.io/ngx-gallery/
- Stars: 636 · Forks: 127
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/murhafsousli-ngx-gallery

## One Angular package covering three overlapping UI patterns

ngx-gallery is described as an Angular gallery, carousel and lightbox, and the repository topics describe the same territory from the outside: angular, carousel, gallery, iframe, image, lightbox, modal, slideshow, video and youtube. Those last two entries matter for scope. A component that opens a YouTube embed or an iframe alongside plain images is a different piece of work from an image grid, and the topic list suggests the library treats them as one feature area rather than three separate widgets. The package is published on npm under the name ng-gallery, so the npm package name and the repository name differ, which is worth knowing before you go looking for a matching folder. The project is MIT licensed, authored by Murhaf Sousli, and ships a live demo plus a StackBlitz playground so you can try the components in a browser before wiring them into an application.

## The documentation is split across a Storybook hub and two archives

The README does not link one documentation site. It splits by version, which tells you the project has been through at least one full rewrite of its public surface. The current documentation is a Storybook Documentation Hub described as offering interactive guides, API references and live component playgrounds, published on the project's GitHub Pages site. Then there are legacy versions: Angular v12 points to an archived documentation website on Netlify, and v11 and below point to a GitHub wiki page. The README frames the split as a choice between looking for the latest features or maintaining an older project, which is a fair way to describe it. For a team still on v12, the practical consequence is that you read one site, and for a team on v11 the source of truth is a wiki, so expectations about API documentation depth should differ by version.

## The current line ships only as prerelease tags

The recent releases tell a clear story about the release state. The newest tags are v13.0.0-next.2 from 2026-09-12, v13.0.0-next.1 from 2026-08-19 and v13.0.0-next.0 from 2026-06-20. There is no stable v13.0.0 tag among them, so the current major line of the library is available only as next prereleases, which in npm terms means a consumer has to opt into a prerelease version rather than taking the default latest. The repository has a CHANGELOG.md and a separate CHANGELOG_legacy.md, matching the documentation split and giving you the upgrade notes for whichever line you are on. The last push was on 2026-10-03, so the code is still moving, and the CI workflow file in the repository and the Codecov badge indicate that builds and coverage are checked on each change.

## Reading package.json to understand the build pipeline

The workspace root is an Angular CLI project rather than the published package itself, and its package.json shows how the library and the demo are kept separate. The project is marked private with the packageManager field pinned to npm@11.16.0, and the scripts are separated into demo builds, library build and docs tasks:

```json
  "scripts": {
    "build": "ng build ng-gallery-demo --ssr=false --prerender=false",
    "build-ssr": "ng build ng-gallery-demo",
    "build-lib": "ng build ng-gallery",
```

The demo build turns server side rendering and prerendering off while the separate build-ssr script does the opposite. The library itself is built with ng build ng-gallery, and a postbuild-lib hook runs a script named copy-readme.mjs, which copies the README into the built output so the published package carries it. Testing has three shapes: ng test ng-gallery with chromium browsers, a headless variant with --no-watch, and a script named simulate-docs.mjs under a test-versions-handler name that exercises the docs version routing. There is also a compodoc invocation that generates API documentation into the projects/ng-gallery directory with private, protected and internal members disabled.

## Angular 22, Material, CDK and the icon set it expects

The dependency list pins the generation of framework the library is built against. The Angular packages, including core, common, compiler, forms, router, platform-browser, platform-server and ssr, all sit at 22.1.6, with @angular/cdk and the Material components at the same version. That pairing is informative, because the CDK overlay and accessibility primitives are what a lightbox is normally built from, and the components package is where the icon set and typography conventions come from. Several FontAwesome packages are listed as well, including the angular-fontawesome wrapper and the free brands, regular and solid icon sets, so the gallery expects iconography to be available from that source rather than shipping its own. Prettier is configured with a print width of 100 and single quotes, with an override that parses HTML files with the angular parser, and eslint.config.js and .editorconfig sit alongside it.

## Building it yourself against a hand-rolled gallery

The realistic alternative is to build the gallery, carousel and lightbox yourself inside your application, or to assemble them from separate smaller Angular packages. The difference in approach is where the overlay and accessibility work lands. A hand-rolled lightbox is a modal with focus trapping, escape handling, scroll locking and a backdrop, and each of those is easy to get subtly wrong and tedious to test. A library that already ships the behaviour for images, iframes and video embeds in one package removes that work, but it also fixes the visual language to whatever the library chose, and you inherit its CSS and its API for the parts you wanted to design differently. The middle case is common: an existing application already uses the Material components, in which case the library's CDK and components alignment is the deciding factor rather than the feature list.

## What to check before you pin a version

There is no installation section in this README, so the package name is the only installation fact you can take from it, and the demo and Storybook links are how you evaluate the component behaviour before committing. The library build outputs to the dist/ directory, and the SSR demo is served from a generated server entry point, which tells you the demo is an Angular application rather than a static page. Two practical warnings follow from the repository layout. The published package is ng-gallery while the workspace project name is ng-gallery-project, so a mismatch between what you install and what you import is easy to author. And since the current major line is prerelease only, pinning a version is a decision you have to make explicitly rather than inheriting from a floating tag. The Contributions.md file and the open issue tracker are the routes for anything the Storybook hub does not answer.

## Conclusion

ngx-gallery fits an Angular team that wants gallery, carousel and lightbox behaviour in one package rather than three, and that is comfortable tracking a prerelease line while its own application is on a recent Angular version. It does not fit a team still on Angular v11 or v12 who needs the old API and the new docs in the same place, and it does not suit a project that requires a stable tagged release today. Verify first which version line your Angular version maps to, since the v13 tags are next prereleases and the v12 documentation lives on a separate archived site, and read the changelog to see what changed between the legacy and current implementations.

## FAQ

### What package name do I install for ngx-gallery?

The npm package is published as ng-gallery, while the workspace project inside the repository is named ng-gallery-project. The library itself is built with ng build ng-gallery.

### Where is the current ngx-gallery documentation?

The current version is documented through a Storybook Documentation Hub with interactive guides, API references and live component playgrounds. Older versions live elsewhere: Angular v12 documentation is on an archived Netlify site and v11 and below on the GitHub wiki page.

### Is ngx-gallery available as a stable release?

The listed tags for the current major version are prereleases: v13.0.0-next.0, v13.0.0-next.1 and v13.0.0-next.2, the newest from 2026-09-12. The last push was on 2026-10-03, and the changelog is split into CHANGELOG.md and CHANGELOG_legacy.md.

### What does ngx-gallery use for overlays and icons?

The dependency list includes @angular/cdk and the Material components package at version 22.1.6 alongside the Angular 22.1.6 packages, plus several FontAwesome packages including the angular-fontawesome wrapper and the free solid, regular and brands icon sets.

## Sources

- [License: MIT](https://github.com/MurhafSousli/ngx-gallery/blob/master/LICENSE)
- [MurhafSousli/ngx-gallery on GitHub](https://github.com/MurhafSousli/ngx-gallery)
- [Project website](https://murhafsousli.github.io/ngx-gallery/)
- [README](https://github.com/MurhafSousli/ngx-gallery/blob/master/README.md)
- [Releases](https://github.com/MurhafSousli/ngx-gallery/releases)

---

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