{"id":44724695,"url":"https://github.com/SeriousSez/ngx-image-magnifier","last_synced_at":"2026-02-17T07:01:23.043Z","repository":{"id":336640151,"uuid":"1150483623","full_name":"SeriousSez/ngx-image-magnifier","owner":"SeriousSez","description":"NPM Package","archived":false,"fork":false,"pushed_at":"2026-02-05T13:43:28.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T23:16:53.003Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@sezsahin/ngx-image-magnifier","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/SeriousSez.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-05T10:32:47.000Z","updated_at":"2026-02-05T13:43:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SeriousSez/ngx-image-magnifier","commit_stats":null,"previous_names":["serioussez/ngx-image-magnifier"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/SeriousSez/ngx-image-magnifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeriousSez%2Fngx-image-magnifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeriousSez%2Fngx-image-magnifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeriousSez%2Fngx-image-magnifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeriousSez%2Fngx-image-magnifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SeriousSez","download_url":"https://codeload.github.com/SeriousSez/ngx-image-magnifier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeriousSez%2Fngx-image-magnifier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29536527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-15T17:00:26.114Z","updated_at":"2026-02-17T07:01:23.034Z","avatar_url":"https://github.com/SeriousSez.png","language":"TypeScript","funding_links":[],"categories":["Third Party Components"],"sub_categories":["Images"],"readme":"# ngx-image-magnifier\n\nA highly performant, customizable Angular image magnifier directive with keyboard modifier support, smart positioning, mobile optimization, and smooth GPU-accelerated animations.\n\n## Features\n\n✨ **Performance-Optimized**\n\n- GPU-accelerated positioning using `transform: translate()`\n- Passive event listeners for better scroll performance\n- Selective keyboard listener attachment (only when needed)\n- CSS containment for isolated rendering\n- RequestAnimationFrame batching for 60fps smooth movement\n\n🎯 **Smart Positioning**\n\n- Intelligent \"auto\" positioning that adapts to viewport constraints\n- 9 manual positioning modes: `right`, `left`, `top`, `bottom`, `bottom-right`, `bottom-left`, `top-right`, `top-left`, `auto`\n- Automatic avoidance of the source image\n- Padding customization for screen edge spacing\n\n📱 **Mobile Optimized**\n\n- Separate configuration for mobile devices\n- Mobile-specific size, ratio, and positioning options\n- Touch-friendly interactions\n- Responsive breakpoint detection (768px)\n\n⌨️ **Keyboard Modifier Support**\n\n- Optional requirement for `shift`, `ctrl`, or `alt` keys\n- Smart hint tooltips with auto-generated text\n- Seamless modifier state tracking\n- Mobile devices ignore modifier requirements\n\n🎨 **Customizable**\n\n- Configurable magnifier size and aspect ratio\n- Custom border radius (including fully rounded circles)\n- Smooth transition animations\n- Custom hint text or disable tooltips entirely\n\n## Installation\n\n```bash\nnpm install @sezsahin/ngx-image-magnifier\n```\n\n## Quick Start\n\nImport the directive and apply it to any image:\n\n```typescript\nimport { Component } from \"@angular/core\";\nimport { ImageMagnifierDirective } from \"@sezsahin/ngx-image-magnifier\";\n\n@Component({\n  selector: \"app-gallery\",\n  standalone: true,\n  imports: [ImageMagnifierDirective],\n  template: ` \u003cimg appImageMagnifier src=\"photo.jpg\" alt=\"Gallery image\" /\u003e `,\n})\nexport class GalleryComponent {}\n```\n\n## Usage Examples\n\n### Basic Magnification (Hover to View)\n\n```html\n\u003cimg appImageMagnifier src=\"product.jpg\" alt=\"Product\" [magnifierSize]=\"300\" /\u003e\n```\n\nBy default, the magnifier shows the image at actual size. To enable zoom:\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"product.jpg\"\n  alt=\"Product\"\n  [magnifierSize]=\"300\"\n  [zoom]=\"2\"\n/\u003e\n```\n\n### With Keyboard Modifier\n\nRequire holding `Ctrl` to magnify:\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"detailed-map.jpg\"\n  alt=\"Map\"\n  [magnifierSize]=\"400\"\n  requireKeyModifier=\"ctrl\"\n/\u003e\n```\n\nMobile users can view the magnifier without holding the modifier.\n\n### Custom Hint Text\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"artwork.jpg\"\n  alt=\"Fine Art\"\n  [magnifierSize]=\"350\"\n  [hintText]=\"'Click to zoom in'\"\n/\u003e\n```\n\n### Disabled Hint Tooltip\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"thumbnail.jpg\"\n  alt=\"Thumbnail\"\n  [magnifierSize]=\"250\"\n  [showHint]=\"false\"\n/\u003e\n```\n\n### Mobile-Specific Configuration\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"responsive-image.jpg\"\n  alt=\"Responsive\"\n  [magnifierSize]=\"400\"\n  [magnifierSizeMobile]=\"250\"\n  [magnifierRatio]=\"'16/9'\"\n  [magnifierRatioMobile]=\"'1/1'\"\n  position=\"auto\"\n  [positionMobile]=\"'bottom'\"\n/\u003e\n```\n\n### Rounded Magnifier\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"profile.jpg\"\n  alt=\"Profile\"\n  [magnifierSize]=\"300\"\n  [rounded]=\"true\"\n/\u003e\n```\n\n### Custom Positioning\n\n```html\n\u003cimg\n  appImageMagnifier\n  src=\"centered-image.jpg\"\n  alt=\"Centered\"\n  position=\"right\"\n  [animateTransition]=\"true\"\n  [padding]=\"30\"\n/\u003e\n```\n\n### Zoom with Focus Control\n\n```html\n\u003c!-- Zoom follows cursor --\u003e\n\u003cimg appImageMagnifier src=\"map.jpg\" alt=\"Map\" [zoom]=\"3\" zoomFocus=\"cursor\" /\u003e\n\n\u003c!-- Zoom with custom focus point --\u003e\n\u003cimg\n  appImageMagnifier\n  src=\"product.jpg\"\n  alt=\"Product\"\n  [zoom]=\"2.5\"\n  zoomFocus=\"custom\"\n  [zoomFocusX]=\"75\"\n  [zoomFocusY]=\"25\"\n/\u003e\n\n\u003c!-- Zoom focused on top-right corner --\u003e\n\u003cimg\n  appImageMagnifier\n  src=\"detail.jpg\"\n  alt=\"Detail\"\n  [zoom]=\"2\"\n  zoomFocus=\"top-right\"\n/\u003e\n```\n\n## API Reference\n\n### @Input Properties\n\n| Property               | Type                                                                                                                                         | Default    | Description                                                                                        |\n| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------- |\n| `magnifierSize`        | `number`                                                                                                                                     | `300`      | Width of magnifier window in pixels                                                                |\n| `magnifierSizeMobile`  | `number \\| null`                                                                                                                             | `null`     | Mobile-specific magnifier size (60% of desktop if not set)                                         |\n| `magnifierRatio`       | `string \\| null`                                                                                                                             | `null`     | Aspect ratio as string, e.g., `'1/1'` or `'16/9'`. If null, uses image's natural ratio             |\n| `magnifierRatioMobile` | `string \\| null`                                                                                                                             | `null`     | Mobile-specific aspect ratio                                                                       |\n| `position`             | `'auto' \\| 'right' \\| 'left' \\| 'top' \\| 'bottom' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-right' \\| 'top-left'`                           | `'auto'`   | Positioning strategy for magnifier placement                                                       |\n| `positionMobile`       | `'auto' \\| 'right' \\| 'left' \\| 'top' \\| 'bottom' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-right' \\| 'top-left' \\| null`                   | `null`     | Mobile-specific positioning (uses desktop position if null)                                        |\n| `animateTransition`    | `boolean`                                                                                                                                    | `true`     | Enable smooth 320ms transitions when moving magnifier                                              |\n| `rounded`              | `boolean`                                                                                                                                    | `false`    | Apply circular border-radius (50%) to magnifier                                                    |\n| `padding`              | `number \\| null`                                                                                                                             | `null`     | Padding from screen edges. Auto-calculated (5% of size + 20px min) if null                         |\n| `requireKeyModifier`   | `'shift' \\| 'ctrl' \\| 'alt' \\| null`                                                                                                         | `null`     | Require holding modifier key to display magnifier. Ignored on mobile                               |\n| `showHint`             | `boolean`                                                                                                                                    | `true`     | Show tooltip hint on first hover (only when modifier required)                                     |\n| `hintText`             | `string \\| null`                                                                                                                             | `null`     | Custom hint text. Auto-generated based on modifier if null                                         |\n| `zoom`                 | `number \\| null`                                                                                                                             | `null`     | Zoom factor for magnification (e.g., `2` for 2x zoom). `null` shows image at actual size           |\n| `zoomFocus`            | `'center' \\| 'cursor' \\| 'top-left' \\| 'top' \\| 'top-right' \\| 'left' \\| 'right' \\| 'bottom-left' \\| 'bottom' \\| 'bottom-right' \\| 'custom'` | `'center'` | Focus point for zoom. `'cursor'` follows mouse, `'center'` centers image, or use specific position |\n| `zoomFocusX`           | `number \\| null`                                                                                                                             | `null`     | Custom X focus percentage (0-100) when `zoomFocus='custom'`                                        |\n| `zoomFocusY`           | `number \\| null`                                                                                                                             | `null`     | Custom Y focus percentage (0-100) when `zoomFocus='custom'`                                        |\n\n## Positioning Strategies\n\n### Auto (Default)\n\nIntelligently places the magnifier to fit the viewport while avoiding the source image. Adapts based on available space.\n\n### Right / Left\n\nPlaces magnifier to the right or left of cursor, vertically centered.\n\n### Top / Bottom\n\nPlaces magnifier above or below cursor, horizontally centered.\n\n### Bottom-Right / Bottom-Left\n\nPlaces magnifier diagonally (right/left with slight downward offset).\n\n### Top-Right / Top-Left\n\nPlaces magnifier diagonally (right/left with slight upward offset).\n\n## Browser Support\n\n- Chrome/Edge: Latest 2 versions\n- Firefox: Latest 2 versions\n- Safari: Latest 2 versions\n- Mobile browsers: iOS Safari 12+, Chrome/Firefox on Android\n\n**SSR Compatible**: The directive uses `isPlatformBrowser` checks for universal rendering support.\n\n## Performance\n\nThe directive is optimized for 60fps smooth interactions:\n\n- **GPU Acceleration**: Uses `transform: translate()` instead of layout-affecting properties\n- **Passive Listeners**: Mouse events don't block scrolling\n- **Event Batching**: Position updates batched with `requestAnimationFrame`\n- **Lazy Listeners**: Keyboard listeners only attached when `requireKeyModifier` is set\n- **CSS Containment**: Rendering isolated from page layout\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Changelog\n\n### 2.0.8-12 (February 05, 2026)\n\n### Fixed\n\n- Aligned package entry points/exports to the actual ng-packagr output paths so module resolution works correctly.. again.\n\n### 2.0.7 (February 05, 2026)\n\n### Fixed\n\n- Improved zoom focus behavior to clamp background position within image boundaries\n  - Prevents blank areas from showing when zoomed in with any focus mode (cursor, custom coordinates, or predefined positions)\n  - Ensures focus point aligns as closely as possible to requested position without exceeding image edges\n  - High zoom values now properly display corresponding image areas while keeping everything in bounds\n\n### 2.0.6 (February 05, 2026)\n\n### Fixed\n\n- Aligned package entry points/exports to the actual ng-packagr output paths so module resolution works correctly.\n\n### 2.0.5 (February 05, 2026)\n\n**Fixed**\n\n- Fixed npm installation issues in Angular packages\n  - Added missing build scripts (`build` and `build:watch`) to package.json\n  - Generated proper dist folder with compiled modules, type definitions, and manifests\n  - Ensured library exports are correctly configured for npm distribution\n\n### 2.0.4 (February 05, 2026)\n\n**Changed**\n\n- Changed default zoom from `2` to `null` (no zoom by default)\n- Images now display at actual size unless zoom property is explicitly set\n- More dynamic and controllable zoom behavior\n\n### 2.0.3 (February 05, 2026)\n\n**Changed**\n\n- Updated docs.\n\n### 2.0.2 (February 05, 2026)\n\n**Changed**\n\n- Updated GitHub repository URL in package.json to the correct link.\n- Updated homepage URL in package.json to the correct link.\n\n### 2.0.1 (January 28, 2026)\n\n**Changed**\n\n- Magnifier now uses zoom scaling when no ratio is set.\n\n### 2.0.0 (January 27, 2026)\n\n**Changed**\n\n- Renamed positioning options:\n  - `right-below` → `bottom-right`\n  - `left-below` → `bottom-left`\n  - `right-above` → `top-right`\n  - `left-above` → `top-left`\n- Documentation and API updated to reflect new names.\n\n### 1.0.5 (January 22, 2026)\n\n**Added**\n\n- New positioning options: `right-above` and `left-above` for both `position` and `positionMobile` inputs.\n- Documentation updated to reflect new options.\n\n### 1.0.4 (January 15, 2026)\n\n**Fixed**\n\n- Fixed TypeScript type compatibility for timeout handling\n  - Changed timeout type from `number` to `ReturnType\u003ctypeof setTimeout\u003e` for proper cross-environment support\n  - Ensures compatibility with both browser and Node.js environments\n\n### 1.0.3 (January 15, 2026)\n\n**Improved**\n\n- Comprehensive memory leak prevention enhancements\n  - Fixed orphaned event listeners that weren't being cleaned up on component destruction\n  - Properly track and clear all timeouts (hint, fadeout, and removal) with proper `ReturnType\u003ctypeof setTimeout\u003e` typing\n  - Store media query listener reference for proper cleanup\n  - Nullify all handler references to enable garbage collection\n  - Improved `ngOnDestroy()` with complete cleanup of keyboard, mouse, and media query listeners\n  - Fixed TypeScript type compatibility for timeout handling\n\n### 1.0.2 (January 15, 2026)\n\n**Fixed**\n\n- Fixed tooltip glitching issue when hovering over images and leaving too quickly\n  - Added guard to prevent duplicate hint instances\n  - Improved hint cleanup logic to prevent visual glitches\n  - Better lifecycle management for hint tooltips\n\n### 1.0.1 (January 10, 2026)\n\n**Fixed**\n\n- Fixed hint tooltip showing on mobile devices\n  - Added mobile device check to prevent tooltips on touch devices\n\n### 1.0.0 (Initial Release)\n\n- Full-featured image magnifier directive\n- GPU-accelerated smooth positioning\n- Keyboard modifier support with smart hints\n- Mobile optimization with responsive sizing\n- Comprehensive customization options\n- Production-ready performance optimizations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSeriousSez%2Fngx-image-magnifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSeriousSez%2Fngx-image-magnifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSeriousSez%2Fngx-image-magnifier/lists"}