{"id":16759923,"url":"https://github.com/bepo65/mat-image-overlay","last_synced_at":"2025-10-16T06:21:28.978Z","repository":{"id":38848197,"uuid":"441925457","full_name":"BePo65/mat-image-overlay","owner":"BePo65","description":"A component for Angular using Angular Material that shows images as overlays. The project contains a library component and a demo project.","archived":false,"fork":false,"pushed_at":"2025-08-14T04:39:26.000Z","size":12432,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T02:49:34.276Z","etag":null,"topics":["angular","icons"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BePo65.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2021-12-26T15:39:06.000Z","updated_at":"2025-08-14T04:38:11.000Z","dependencies_parsed_at":"2023-11-02T06:27:12.182Z","dependency_job_id":"88e18510-8825-443c-9a43-1c53f6503cd1","html_url":"https://github.com/BePo65/mat-image-overlay","commit_stats":{"total_commits":260,"total_committers":1,"mean_commits":260.0,"dds":0.0,"last_synced_commit":"297d5b88905b40b7688fbb4a1707c94233b26a68"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/BePo65/mat-image-overlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BePo65%2Fmat-image-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BePo65%2Fmat-image-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BePo65%2Fmat-image-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BePo65%2Fmat-image-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BePo65","download_url":"https://codeload.github.com/BePo65/mat-image-overlay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BePo65%2Fmat-image-overlay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279162119,"owners_count":26117113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"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","icons"],"created_at":"2024-10-13T04:09:20.278Z","updated_at":"2025-10-16T06:21:28.965Z","avatar_url":"https://github.com/BePo65.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mat-Image-Overlay\n![Version](https://img.shields.io/badge/version-17.0.11-blue.svg?cacheSeconds=2592000)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kefranabg/readme-md-generator/blob/master/LICENSE)\n![Angular version](https://img.shields.io/github/package-json/dependency-version/bepo65/mat-image-overlay/@angular/core?color=red\u0026label=Angular\u0026logo=angular\u0026logoColor=red)\n![GitHub package.json dependency version (prod)](https://img.shields.io/github/package-json/dependency-version/bepo65/mat-image-overlay/@angular/material?color=red\u0026label=Angular-Material\u0026logo=angular\u0026logoColor=red)\n\nAn [Angular Material](https://material.angular.io/) based standalone component that shows images in an overlay.\nThe component is based on Rafasantos [angular-material-image-overlay](https://github.com/rafasantos/angular-material-image-overlay).\n\n## Demo\n Try out the [demo page](https://bepo65.github.io/mat-image-overlay/).\n\n![Screenshot](assets/screenshot.jpg \"Screenshot of the demo page\")\n\n## Quick Start\nInstall the package:\n\n```\nnpm install mat-image-overlay\n```\n\nConfigure your angular application module (e.g: `app.module.ts`):\n```\n...\nimport { MatImageOverlayModule } from 'mat-image-overlay';\n\n@NgModule({\n  ...\n  imports: [\n    ...\n    MatImageOverlayModule\n  ]\n})\nexport class AppModule { }\n```\n\nDefine a class based on MatImageDetailsProvider to get information about the images and create an instance of it in the mat-image-overlay configuration. Examples for classes based on MatImageDetailsProvider can be found in the 'examples/provider' directory of the mat-image-overlay component.\n```\nimages = [\n    'https://url/of/first/image.jpg',\n    'https://url/of/second/image.jpg',\n    'https://url/of/third/image.jpg',\n    'https://url/of/fourth/image.jpg'\n];\n\nconstructor(private imageOverlay: MatImageOverlay) {\n}\n\nopenImageOverlay(imageIndex?: number): void {\n  const config = {\n    imageDetails: new StringSourceImageDetailsProvider(this.images),\n    startImageIndex: imageIndex,\n    backdropClass: 'demo-backdrop-class'\n  } as MatImageOverlayConfig;\n  const imageOverlayRef = this.imageOverlay.open(config);\n}\n```\n\nOpen the overlay via a clickable element in your html template (e.g. `app.component.html`)\n```html\n  \u003cp\u003e\n    Click \u003ca href=\"#\" (click)=\"openImageOverlay()\"\u003ehere to open the overlay\u003c/a\u003e\n  \u003c/p\u003e\n```\n## Navigation\nWhen the overlay is shown, the keyboard can be used to navigate between the images (even when no navigational buttons are displayed on the image). The following keys are available:\n\n| key | function |\n|-----|----------|\n| Arrow Right | show next image |\n| Arrow Down | show next image |\n| Arrow Left | show previous image |\n| Arrow Up | show previous image |\n| Home | show first image |\n| End | show last image |\n| Escape | close overlay |\n\n## Used assets\nThe component is based on Angular Material and uses [Google Fonts](https://fonts.google.com/specimen/Roboto) and [Google Material Icons](https://google.github.io/material-design-icons/#icon-font-for-the-web).\nBoth fonts are part of the project and not fetched via https.\n\nSome special icons are stored in the code as strings representing the icons as svg graphics.\n\n## Mat-Image-Overlay Demo\nDemo project to show how `mat-image-overlay` works.\n\n```\ngit clone git@github.com:BePo65/mat-image-overlay.git\ncd mat-image-overlay\nnpm start\n```\n\nNavigate to http://localhost:4200\n\n# API reference for Mat-Image-Overlay\n\n## Services\n### MatImageOverlay\nService to open Mat-Image-Overlay as a modal overlay.\n\n**Properties**\n| Name  | Description |\n|---|---|\n| imageOverlayRef: MatImageOverlayRef \u0026#124; undefined | Reference of the opened image overlay. |\n| afterOpened: Subject\u0026lt;MatImageOverlayRef\u0026gt; | Stream that gets notified when the image overlay has been opened. |\n| afterClosed: Subject\u0026lt;number\u0026gt; | Stream that gets notified when the image overlay has been closed. |\n\n**Methods**\n| open | |\n|---|--|\n| Opens the image overlay. | |\n| *Parameters* | |\n| config\u003cbr\u003eMatImageOverlayConfig | Extra configuration options. |\n| *Returns* | |\n| MatImageOverlayRef | Reference to opened image overlay.\n\n| imageOverlayExists | |\n|---|--|\n| Checks whether the image overlay already exists. | |\n| *Returns* | |\n| boolean | true = image overlay exists |\n\n## Interfaces\n### MatImageOverlayConfig\nConfiguration for opening a modal image overlay with the MatImageOverlay service.\n\n**Properties**\n| Name  | Description |\n|---|---|\n| imageDetails | Instance of a class derived from MatImageDetailsProvider. |\n| startImageIndex | Index of the first image to be displayed (0 based). |\n| backdropClass | CSS class to add to the backdrop, replacing the default backdrop css. This CSS class must be in the global styles of the application.\u003cbr\u003eDefault style is '`background: rgba(0 0 0 / 32%);`'\u003cbr\u003eOptional parameter. |\n| margin | Minimal margin in px around the loaded image.\u003cbr\u003eDefault value: 32\u003cbr\u003eOptional parameter. |\n| overlayButtonsStyle | Style of the buttons in the image overlay (using enum ElementDisplayStyle: never, onHover, always).\u003cbr\u003eDefault value: ElementDisplayStyle.onHover.\u003cbr\u003eOptional parameter. |\n| descriptionDisplayStyle | Style of the image description in the image overlay (using enum ElementDisplayStyle: never, onHover, always). Using this option requires a property named 'description' in the data source.\u003cbr\u003eDefault value: ElementDisplayStyle.never.\u003cbr\u003eOptional parameter. |\n| descriptionDisplayPosition | Position of the image description in the image overlay (using enum ElementDisplayPosition: bottomLeft, bottomCenter, bottomRight, topLeft, topCenter, topRight). Using this option requires a property named 'description' in the data source.\u003cbr\u003eDefault value: ElementDisplayPosition.bottomRight.\u003cbr\u003eOptional parameter. |\n| imageClickedAdditionalData | Object with arbitrary data that will be returned by the imageClicked event (added to the data returned by the 'imageDetails.imageInformation' method).\u003cbr\u003eOptional parameter. |\n\n### MatImageDetailsProvider\nAbstract base class to be derived by a real image details provider. This class is used to get all the required information about an image.\n\n**Properties**\n| Name  | Description |\n|---|---|\n| numberOfImages | Number of images that can be displayed (this property is readonly). |\n\n**Methods**\n| urlForImage | |\n|---|--|\n| Gets the url for an image. | |\n| *Parameters* | |\n| imageIndex | Index of the image to be displayed (0 based). |\n| *Returns* | |\n| string | Url for the image to be displayed. |\n\n| descriptionForImage | |\n|---|--|\n| Gets the description for an image. | |\n| *Parameters* | |\n| imageIndex | Index of the image to be displayed (0 based). |\n| *Returns* | |\n| string | Url for the image to be displayed. |\n\n| imageInformation | |\n|---|--|\n| Gets a record that contains information about an image. | The returned object is part of the data returned by the imageClicked event. |\n| *Parameters* | |\n| imageIndex | Index of the clicked image (0 based). |\n| *Returns* | |\n| Record\u003cstring, unknown\u003e | Object with additional data about the image. |\n\n### ThumbnailProvider\nInterface to add the handling of thumbnail images to a class derived from MatImageDetailsProvider.\n\n**Properties**\n| Name  | Description |\n|---|---|\n| thumbnailHeight | Height of the thumbnail images in px. |\n\n**Methods**\n| urlForThumbnail | |\n|---|--|\n| Gets the url for a thumbnail image. | |\n| *Parameters* | |\n| imageIndex | Index of the thumbnail image to be displayed (0 based). |\n| *Returns* | |\n| string | Url for the thumbnail image to be displayed. |\n\n## Classes\n### MatImageOverlayRef\nReference to an image overlay opened via the MatImageOverlay service.\n\n**Properties**\n| Name  | Description |\n|---|---|\n| numberOfImages | number of images that can be displayed. |\n| keydownEvents$ | Observable that is notified by keydown events on the overlay. Navigation buttons don't get emitted. |\n\n**Methods**\n| afterOpened | |\n|---|--|\n| Gets an observable that is notified when the image overlay is finished opening. | |\n| *Returns* | |\n| Observable\u0026lt;void\u0026gt; | Observable that fires, when the overlay has been opened. |\n\n| afterClosed | |\n|---|--|\n| Gets an observable that is notified when the image overlay is finished closing. | |\n| *Returns* | |\n| Observable\u0026lt;number\u0026gt; | Observable that returns the index of the last image displayed. |\n\n| imageChanged | |\n|---|--|\n| Gets an observable that is notified when a new image has been selected. | |\n| *Returns* | |\n| Observable\u0026lt;number\u0026gt; | Observable that returns the index of the image displayed. |\n\n| imageClicked | |\n|---|--|\n| Gets an observable that is notified when an image has been clicked. | |\n| *Returns* | |\n| Observable\u0026lt;ImageClickedEvent\u0026gt; | Observable that returns the object with data of the clicked image and the imageClickedConfiguration object from the config object. |\n\n| gotoNextImage | |\n|---|--|\n| Display the next image in the datasource. | |\n\n| gotoPreviousImage | |\n|---|--|\n| Display the previous image in the datasource. | |\n\n| gotoFirstImage | |\n|---|--|\n| Display the first image in the datasource. | |\n\n| gotoLastImage | |\n|---|--|\n| Display the last image in the datasource. | |\n\n| gotoImage | |\n|---|--|\n| Display the image in the datasource selected by the imageIndex. | |\n| *Parameters* | |\n| imageIndex | Index of the image to be displayed. |\n\n| close | |\n|---|--|\n| Close the image overlay. | |\n\n# API reference for Mat-Image-Overlay testing\n\n```typescript\nimport { MatImageOverlayHarness } from 'mat-image-overlay/testing';\n```\n## Classes\n### MatImageOverlayHarness extends ContentContainerComponentHarness\nHarness for interacting with a standard MatImageOverlay in tests.\n\n**Properties**\n| Name  | Description |\n|---|---|\n| static hostSelector: '.mat-image-overlay-container' | The selector for the host element of a MatImageOverlay instance. |\n\n**Methods**\n| async overlayIsLoaded | |\n|---|--|\n| Gets a promise that fulfills to true, when the image overlay is visible. | |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise that fulfills to a flag that shows, if the image overlay is visible.\n\n| async close | |\n|---|--|\n| Closes the image overlay by pressing escape. | |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that fulfills, when the action completes.\n\n| async clickBackdrop | |\n|---|--|\n| Closes the image overlay by clicking the backdrop of the image overlay. | |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that fulfills, when the action completes.\n\n| async buttonCloseVisible | |\n|---|--|\n| Gets a promise that fulfills to true, when the 'close' button is visible. | |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise that fulfills to a flag that shows, if the 'close' button is visible.\n\n| async buttonPreviousVisible | |\n|---|--|\n| Gets a promise that fulfills to true, when the 'previous' button is visible. | |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise that fulfills to a flag that shows, if the 'previous' button is visible.\n\n| async buttonNextVisible | |\n|---|--|\n| Gets a promise that fulfills to true, when the 'next' button is visible. | |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise that fulfills to a flag that shows, if the 'next' button is visible.\n\n| async descriptionVisible | |\n|---|--|\n| Gets a promise that fulfills to true, when the 'description' of the image is visible. | |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise that fulfills to a flag that shows, if the 'description' is visible.\n\n| async clickCloseButton | |\n|---|--|\n| Clicks the 'close overlay' button of the image overlay. | |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that fulfills, when the action completes.\n\n| async clickPreviousButton | |\n|---|--|\n| Clicks the 'goto previous image' button of the image overlay. | |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that fulfills, when the action completes.\n\n| async clickNextButton | |\n|---|--|\n| Clicks the 'goto next image' button of the image overlay. | |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that fulfills, when the action completes.\n\n| async figureHover | |\n|---|--|\n| Sets the figure tag of the overlay (the content of the overlay) into the hover state. | |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that fulfills, when the action completes.\n\n| async imageUrl | |\n|---|--|\n| Gets a promise that fulfills to the url of the current image in the overlay. | |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise that fulfills to the url of the image or to an empty string.\n\n| async sendKeys | |\n|---|--|\n| Send keys to the overlay. | |\n| *Parameters* | |\n| ...keys | Array of 'TestKey' to be sent. Possible values are the arrow keys, the home and the end key. |\n| *Returns* | |\n| Promise\u0026lt;void\u0026gt; | Promise that resolves when the action completes.\n\n| async hasBackdropClass | |\n|---|--|\n| Gets a promise that fulfills to true, when the backdrop contains the given css class. | |\n| *Parameters* | |\n| classname | Name of the css class to be evaluated. |\n| *Returns* | |\n| Promise\u0026lt;boolean\u0026gt; | Promise fulfills to a flag that shows, if the backdrop contains the given css class.\n\n# Development\nBuild the library and the demo project:\n```\nnpm run build\n```\n\nLint the library,  the demo project with eslint and the scss files with stylelint:\n```\nnpm run lint\nnpm run lint:scss\n```\n\nTest the library and the demo project:\n```\nnpm run test\n```\n\nRun component tests for the library project with cypress once (e.g. for CI scenarios):\n```\nnpm run ct\n```\n\nRun end to end tests for the demo project with cypress once (e.g. for CI scenarios):\n```\nnpm run e2e\n```\nThe script 'build:ghpages' is used by the github automation to publish the demo to github pages, when the master branch is updated.\n\n# Contributing\n## Changelog\nThe project uses 'standard-version' to create the changelog. To enable this system, commit messages are linted before commits are executed by git.\n\n**The structure of commit messages is**:\n```\n  \u003cheader\u003e\n  \u003cBLANK LINE\u003e\n  \u003cbody\u003e\n  \u003cBLANK LINE\u003e\n  \u003cfooter\u003e\n```\n\n**header**\n```\n  \u003ctype\u003e(\u003cscope\u003e): \u003cshort summary\u003e\n```\n  \ntype and scope\n  - build: Changes that affect the build system or external dependencies (example scope: npm)\n  - docs: Documentation only changes\n  - feat: A new feature\n  - fix: A bug fix\n  - perf: A code change that improves performance\n  - refactor: A code change that neither fixes a bug nor adds a feature\n  - test: Adding missing tests or correcting existing tests (example scopes: demo, lib, e2e)\n\n**footer**\n```\n  BREAKING CHANGE: ... (requires MAJOR in Semantic Versioning)\n```\n\nFor details of the commit messages format see [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit).\n\n# License\n\nCopyright © 2024 [Bernhard Pottler](https://github.com/BePo65).\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\nThis project uses the fonts '[Roboto](https://fonts.google.com/specimen/Roboto/about)' and '[Material Icons](https://github.com/google/material-design-icons)' from the [Google Fonts Library](https://fonts.google.com/) that are licensed under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt).\n\n## Hints\nAs `eslint` V9 is not supported by angular@17 and also requires a fundamental change to the configuration files, the update will be done in a later version.\n\nAs a consequence the package `eslint-plugin-cypress` cannot be updated to a version 4.x (as this version has a peerDependency of eslint \u003e= 9).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbepo65%2Fmat-image-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbepo65%2Fmat-image-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbepo65%2Fmat-image-overlay/lists"}