{"id":20520,"library":"retinajs","title":"retinajs","description":"A JavaScript library that automatically serves high-resolution image variants (e.g., @2x, @3x) to devices with retina or high-DPI displays. Current stable version is 2.1.3, released in maintenance mode. It supports multiple pixel density levels and can swap img src attributes, inline background images, or generate CSS media queries. Unlike alternatives that require build-time processing or polyfills, retina.js works client-side with zero configuration for standard image naming conventions. It integrates with Sass, Less, and Stylus for CSS background images.","status":"active","version":"2.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/strues/retinajs","tags":["javascript","retina","images","@2x","@3x","retina.js"],"install":[{"cmd":"npm install retinajs","lang":"bash","label":"npm"},{"cmd":"yarn add retinajs","lang":"bash","label":"yarn"},{"cmd":"pnpm add retinajs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"v2 is ESM only; CJS require will fail.","wrong":"const retinajs = require('retinajs')","symbol":"default (retinajs function)","correct":"import retinajs from 'retinajs'"},{"note":"Since v2 the default export is the function itself, but named export also exists. Prefer default for simplicity.","wrong":"import retinajs from 'retinajs'","symbol":"retinajs as named import","correct":"import { retinajs } from 'retinajs'"},{"note":"In browser, the library sets window.retinajs. Call with a selector or element collection.","wrong":"retinajs()","symbol":"retina (global)","correct":"window.retinajs('img')"},{"note":"Type imports are available for TS users; value import will fail at runtime.","wrong":"import { RetinaOptions } from 'retinajs'","symbol":"types","correct":"import type { RetinaOptions } from 'retinajs'"}],"quickstart":{"code":"// Install: npm install retinajs\n\nimport retinajs from 'retinajs';\n\n// Option 1: Auto-process all images with data-rjs attribute\ndocument.addEventListener('DOMContentLoaded', () => {\n  retinajs();\n});\n\n// Option 2: Process specific elements\nconst images = document.querySelectorAll('img[data-rjs]');\nretinajs(images);\n\n// HTML example:\n// <img src=\"normal.png\" data-rjs=\"2\" />\n// will become <img src=\"normal@2x.png\" /> on retina devices\n\n// For inline backgrounds:\n// <div style=\"background: url(normal.png)\" data-rjs=\"2\"></div>","lang":"typescript","description":"Shows how to install, import, and use retinajs to auto-swap images on retina displays."},"warnings":[{"fix":"Use `import retinajs from 'retinajs'` instead of `require('retinajs')`. The `data-at2x` attribute is replaced by `data-rjs`.","message":"v2.0.0 is a complete rewrite. The default export changed from a jQuery plugin to a standalone function.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove jQuery dependency and chain calls. Use `retinajs(selector)` directly.","message":"In v2.0.0, the function `retinajs()` no longer returns a jQuery object and does not require jQuery.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace `data-at2x` with `data-rjs` attribute with a number (resolution cap) or a URL string.","message":"The `data-at2x` attribute is deprecated and removed in v2.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Upgrade to v2.1.0+ or pass an explicit collection of unprocessed images.","message":"If you call `retinajs()` multiple times, it may re-process already swapped images, causing duplicate suffixes (e.g., `image@2x@2x.png`). Fixed in v2.1.0.","severity":"gotcha","affected_versions":">=2.0.0 <2.1.0"},{"fix":"Ensure high-res variants are uploaded before using retina.js.","message":"The library expects images to exist at the server with the correct naming (e.g., `image@2x.png`). It does not generate images.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use ES6 import: `import retinajs from 'retinajs'` or configure bundler to resolve ESM.","cause":"Using CommonJS `require('retinajs')` with the ESM-only v2 package.","error":"Uncaught TypeError: retinajs is not a function"},{"fix":"Upload the @2x, @3x variants to the server, or adjust the data-rjs attribute to point to a valid URL.","cause":"The high-res image file does not exist at the expected path.","error":"net::ERR_ABORTED 404 (Not Found) for image@2x.png"},{"fix":"Ensure the script is loaded before calling retinajs. Use `<script src=\"retinajs.js\"></script>` and call after DOM ready.","cause":"Using the library in a browser without importing it properly or before the script loads.","error":"retinajs is not defined"},{"fix":"Verify that the selector matches existing elements, or pass a valid NodeList or array.","cause":"Passing an empty or invalid selector/collection to retinajs().","error":"Cannot read property 'src' of null"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}