{"id":51866065,"url":"https://github.com/design4pro/ngx-image-gallery","last_synced_at":"2026-07-24T16:04:13.979Z","repository":{"id":366593830,"uuid":"1271032506","full_name":"design4pro/ngx-image-gallery","owner":"design4pro","description":"Angular simple image gallery","archived":false,"fork":false,"pushed_at":"2026-07-14T21:05:00.000Z","size":401,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-14T21:09:04.602Z","etag":null,"topics":["angular","gallery","image"],"latest_commit_sha":null,"homepage":"https://design4pro.github.io/ngx-image-gallery/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/design4pro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-16T09:14:33.000Z","updated_at":"2026-07-14T20:14:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/design4pro/ngx-image-gallery","commit_stats":null,"previous_names":["design4pro/ngx-image-gallery"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/design4pro/ngx-image-gallery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fngx-image-gallery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fngx-image-gallery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fngx-image-gallery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fngx-image-gallery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/design4pro","download_url":"https://codeload.github.com/design4pro/ngx-image-gallery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/design4pro%2Fngx-image-gallery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35847531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-24T02:00:07.870Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","gallery","image"],"created_at":"2026-07-24T16:04:08.887Z","updated_at":"2026-07-24T16:04:13.951Z","avatar_url":"https://github.com/design4pro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @design4pro/ngx-image-gallery\n\n[![Angular 20–22](https://img.shields.io/badge/Angular-20--22-DD0031?logo=angular\u0026logoColor=white)](https://angular.dev/)\n[![Deploy GitHub Pages](https://github.com/design4pro/ngx-image-gallery/actions/workflows/pages.yml/badge.svg)](https://github.com/design4pro/ngx-image-gallery/actions/workflows/pages.yml)\n[![GitHub release](https://img.shields.io/github/v/release/design4pro/ngx-image-gallery)](https://github.com/design4pro/ngx-image-gallery/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](projects/ngx-image-gallery/LICENSE)\n\nA native Angular image gallery with a responsive lightbox, progressive image loading, touch gestures, zoom, and accessible defaults.\n\n[Live demo](https://design4pro.github.io/ngx-image-gallery/) ·\n[Documentation](https://design4pro.github.io/ngx-image-gallery/docs/installation) ·\n[Examples](https://design4pro.github.io/ngx-image-gallery/examples/custom-properties) ·\n[Releases](https://github.com/design4pro/ngx-image-gallery/releases)\n\n## Why ngx-image-gallery?\n\n- Standalone Angular directives with a small, typed API.\n- Smooth lightbox opening from the selected thumbnail.\n- Progressive loading with thumbnail-first rendering.\n- Swipe navigation, pinch and wheel zoom, double-click zoom, and bounded panning.\n- Accessible modal behavior, keyboard navigation, focus trapping, focus restoration, and reduced-motion support.\n- Optional counters, thumbnail navigation, custom controls, and custom Angular slide content.\n- CSS custom properties and stable class hooks for consumer-owned styling.\n- Opt-in enhancement of trusted article or CMS-rendered image markup.\n- Optional Angular Router integration through a secondary entrypoint.\n- No runtime dependency on PhotoSwipe, Angular Material, Tailwind, Bootstrap, CDK Overlay, or another UI framework.\n\n## Compatibility\n\n| Dependency        | Supported version            |\n| ----------------- | ---------------------------- |\n| `@angular/core`   | `\u003e=20.0.0 \u003c23.0.0`           |\n| `@angular/common` | `\u003e=20.0.0 \u003c23.0.0`           |\n| `@angular/router` | `\u003e=20.0.0 \u003c23.0.0`, optional |\n\nThe package is standalone-first and does not provide an `NgModule`. Angular Router is required only when importing from `@design4pro/ngx-image-gallery/router`.\n\n## Installation\n\nThe package is published to GitHub Packages. Configure the `@design4pro` scope in your project-level `.npmrc`:\n\n```ini\n@design4pro:registry=https://npm.pkg.github.com\n```\n\nAuthenticate with your GitHub username and a classic personal access token with `read:packages` permission:\n\n```bash\nnpm login --scope=@design4pro --auth-type=legacy --registry=https://npm.pkg.github.com\n```\n\nThen install the package:\n\n```bash\nnpm install @design4pro/ngx-image-gallery\n```\n\nSee [GitHub Packages authentication](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages) for CI and organization-specific setup.\n\n## Quick start\n\nImport the gallery and item directives into a standalone component, then describe each image with a typed item.\n\n```ts\nimport { Component } from '@angular/core';\nimport {\n  NgxImageGalleryDirective,\n  NgxImageGalleryItemDirective,\n  type NgxImageGalleryItem,\n  type NgxImageGalleryOptionsInput,\n} from '@design4pro/ngx-image-gallery';\n\n@Component({\n  selector: 'app-photo-gallery',\n  standalone: true,\n  imports: [NgxImageGalleryDirective, NgxImageGalleryItemDirective],\n  templateUrl: './photo-gallery.component.html',\n})\nexport class PhotoGalleryComponent {\n  readonly photos: NgxImageGalleryItem[] = [\n    {\n      id: 'mountain-lake',\n      fullSrc: '/photos/mountain-lake-full.jpg',\n      thumbSrc: '/photos/mountain-lake-thumb.jpg',\n      alt: 'Mountain lake at sunrise',\n      width: 2400,\n      height: 1600,\n    },\n    {\n      id: 'forest-path',\n      fullSrc: '/photos/forest-path-full.jpg',\n      thumbSrc: '/photos/forest-path-thumb.jpg',\n      alt: 'Forest path after rain',\n      width: 2400,\n      height: 1600,\n    },\n  ];\n\n  readonly galleryOptions: NgxImageGalleryOptionsInput = {\n    showThumbnails: true,\n  };\n}\n```\n\n```angular\n\u003cdiv ngxImageGallery [ngxImageGallery]=\"galleryOptions\"\u003e\n  @for (photo of photos; track photo.id) {\n    \u003ca [href]=\"photo.fullSrc\" [ngxImageGalleryItem]=\"photo\"\u003e\n      \u003cimg [src]=\"photo.thumbSrc\" [alt]=\"photo.alt\" /\u003e\n    \u003c/a\u003e\n  }\n\u003c/div\u003e\n```\n\nThe anchor keeps a useful native fallback and supports modified clicks such as \u003ckbd\u003eCtrl\u003c/kbd\u003e/\u003ckbd\u003eCmd\u003c/kbd\u003e + click. No gallery stylesheet import is required; the library supplies minimal default lightbox styles when the first gallery opens.\n\n## Customize without framework lock-in\n\nThe default lightbox is deliberately minimal. Applications own thumbnail layout and can customize generated lightbox elements with CSS custom properties, additive classes, or a custom Angular template.\n\n```ts\nreadonly galleryOptions: NgxImageGalleryOptionsInput = {\n  classes: {\n    overlay: 'brand-lightbox',\n  },\n};\n```\n\n```css\n.brand-lightbox {\n  --ngx-image-gallery-backdrop-background: rgb(5 10 20 / 92%);\n  --ngx-image-gallery-control-background: rgb(255 255 255 / 16%);\n  --ngx-image-gallery-control-border-radius: 999px;\n  --ngx-image-gallery-control-focus-outline: 2px solid #38bdf8;\n  --ngx-image-gallery-thumbnail-active-border-color: #38bdf8;\n}\n```\n\nTailwind and other utility frameworks can be used by consuming applications, but they are not required by the library.\n\n## Accessibility and interaction\n\nThe generated lightbox provides modal dialog semantics, focus management, inactive-slide hiding, scroll locking, loading and error announcements, and reduced-motion support.\n\nDefault keyboard controls:\n\n| Key                                                | Action                     |\n| -------------------------------------------------- | -------------------------- |\n| \u003ckbd\u003eEscape\u003c/kbd\u003e                                  | Close                      |\n| \u003ckbd\u003eArrowLeft\u003c/kbd\u003e / \u003ckbd\u003eArrowRight\u003c/kbd\u003e       | Previous / next            |\n| \u003ckbd\u003e+\u003c/kbd\u003e or \u003ckbd\u003e=\u003c/kbd\u003e                       | Zoom in                    |\n| \u003ckbd\u003e-\u003c/kbd\u003e                                       | Zoom out                   |\n| \u003ckbd\u003e0\u003c/kbd\u003e                                       | Reset zoom                 |\n| \u003ckbd\u003eTab\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eTab\u003c/kbd\u003e | Move within the focus trap |\n\nGenerated UI uses English labels by default. Applications can localize dialog, control, counter, thumbnail, loading, error, and item labels through typed gallery options.\n\n## Angular Router integration\n\nRouter behavior lives in the optional `@design4pro/ngx-image-gallery/router` secondary entrypoint, keeping the primary entrypoint independent of Angular Router.\n\n```ts\nimport { NgxImageGalleryCloseOnNavigationDirective } from '@design4pro/ngx-image-gallery/router';\n```\n\n```html\n\u003cdiv ngxImageGallery ngxImageGalleryCloseOnNavigation\u003e\n  \u003c!-- gallery items --\u003e\n\u003c/div\u003e\n```\n\nThe directive closes the gallery-owned lightbox when Angular Router navigation starts, including browser history navigation.\n\n## Documentation\n\n| Topic              | Guide                                                                                                        |\n| ------------------ | ------------------------------------------------------------------------------------------------------------ |\n| Installation       | [Install and provide defaults](https://design4pro.github.io/ngx-image-gallery/docs/installation)             |\n| Usage              | [Directive markup and item data](https://design4pro.github.io/ngx-image-gallery/docs/usage)                  |\n| API options        | [Gallery, item, and router options](https://design4pro.github.io/ngx-image-gallery/docs/options)             |\n| Styling            | [Custom properties and class hooks](https://design4pro.github.io/ngx-image-gallery/docs/styling)             |\n| Custom UI          | [Custom controls and slide content](https://design4pro.github.io/ngx-image-gallery/docs/custom-lightbox)     |\n| Accessibility      | [Semantics, keyboard support, and labels](https://design4pro.github.io/ngx-image-gallery/docs/accessibility) |\n| Router integration | [Close on route changes](https://design4pro.github.io/ngx-image-gallery/docs/router-close)                   |\n\nExplore working examples for [CSS custom properties](https://design4pro.github.io/ngx-image-gallery/examples/custom-properties), [Tailwind 4](https://design4pro.github.io/ngx-image-gallery/examples/tailwind), [custom Angular content](https://design4pro.github.io/ngx-image-gallery/examples/custom-content), [auto-discovery](https://design4pro.github.io/ngx-image-gallery/examples/auto-discovery), and [router integration](https://design4pro.github.io/ngx-image-gallery/examples/router-close).\n\nThe [package README](projects/ngx-image-gallery/README.md) contains the complete consumer reference, including configuration, auto-discovery boundaries, custom templates, image URL safety, and all styling hooks.\n\n## Repository structure\n\n| Path                            | Purpose                                                  |\n| ------------------------------- | -------------------------------------------------------- |\n| `projects/ngx-image-gallery`    | Angular library and package documentation.               |\n| `projects/demo`                 | Documentation site and live gallery examples.            |\n| `DESIGN.md`                     | Architecture, API, styling, and accessibility decisions. |\n| `.github/workflows/pages.yml`   | GitHub Pages build and deployment.                       |\n| `.github/workflows/release.yml` | Package release workflow.                                |\n\nRead [DESIGN.md](DESIGN.md) before changing library architecture or public APIs. The library intentionally remains directive-based, UI-framework independent, and consumer-styled.\n\n## Local development\n\nInstall dependencies, build the library, and start the documentation site:\n\n```bash\nnpm ci\nnpx ng build ngx-image-gallery\nnpx ng serve demo\n```\n\nOpen `http://localhost:4200/`.\n\nThe demo imports `ngx-image-gallery` from `dist/ngx-image-gallery`, so rebuild the library before testing demo changes that depend on library code.\n\n## Verification\n\nRun the repository checks in this order:\n\n```bash\nnpx prettier --check .\nnpx ng test ngx-image-gallery --watch=false\nnpx ng build ngx-image-gallery\nnpx ng test demo --watch=false\nnpx ng build demo --configuration development\n```\n\nFor the GitHub Pages artifact:\n\n```bash\nnpx ng build demo --configuration production --base-href /ngx-image-gallery/\ncp dist/demo/browser/index.html dist/demo/browser/404.html\n```\n\n## Package artifact\n\nBuild the Angular Package Format output before packing or publishing:\n\n```bash\nnpx ng build ngx-image-gallery\nnpm pack ./dist/ngx-image-gallery --dry-run\n```\n\nDo not pack `projects/ngx-image-gallery` directly; it is the source package, not the built artifact.\n\n## Support\n\n- Browse the [documentation and live examples](https://design4pro.github.io/ngx-image-gallery/).\n- Check [existing issues](https://github.com/design4pro/ngx-image-gallery/issues) before reporting a problem.\n- Include a minimal reproduction, Angular version, browser, and expected behavior in new bug reports.\n\n## Attribution\n\nThis package adapts selected PhotoSwipe v5 interaction and layout ideas for Angular. PhotoSwipe is MIT licensed. See [THIRD_PARTY_NOTICES.md](projects/ngx-image-gallery/THIRD_PARTY_NOTICES.md).\n\n## License\n\nMIT. See [LICENSE](projects/ngx-image-gallery/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesign4pro%2Fngx-image-gallery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdesign4pro%2Fngx-image-gallery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesign4pro%2Fngx-image-gallery/lists"}