retinajs

2.1.3 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Uncaught TypeError: retinajs is not a function ↓

cause Using CommonJS `require('retinajs')` with the ESM-only v2 package.

fix

Use ES6 import: import retinajs from 'retinajs' or configure bundler to resolve ESM.

error net::ERR_ABORTED 404 (Not Found) for image@2x.png ↓

cause The high-res image file does not exist at the expected path.

fix

Upload the @2x, @3x variants to the server, or adjust the data-rjs attribute to point to a valid URL.

error retinajs is not defined ↓

cause Using the library in a browser without importing it properly or before the script loads.

fix

Ensure the script is loaded before calling retinajs. Use <script src="retinajs.js"></script> and call after DOM ready.

error Cannot read property 'src' of null ↓

cause Passing an empty or invalid selector/collection to retinajs().

fix

Verify that the selector matches existing elements, or pass a valid NodeList or array.

Warnings

breaking v2.0.0 is a complete rewrite. The default export changed from a jQuery plugin to a standalone function. ↓

fix Use `import retinajs from 'retinajs'` instead of `require('retinajs')`. The `data-at2x` attribute is replaced by `data-rjs`.

breaking In v2.0.0, the function `retinajs()` no longer returns a jQuery object and does not require jQuery. ↓

fix Remove jQuery dependency and chain calls. Use `retinajs(selector)` directly.

deprecated The `data-at2x` attribute is deprecated and removed in v2. ↓

fix Replace `data-at2x` with `data-rjs` attribute with a number (resolution cap) or a URL string.

gotcha 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. ↓

fix Upgrade to v2.1.0+ or pass an explicit collection of unprocessed images.

gotcha The library expects images to exist at the server with the correct naming (e.g., `image@2x.png`). It does not generate images. ↓

fix Ensure high-res variants are uploaded before using retina.js.

Install

npm install retinajs

yarn add retinajs

pnpm add retinajs

Imports

default (retinajs function)
wrong
```
const retinajs = require('retinajs')
```
correct
```
import retinajs from 'retinajs'
```
v2 is ESM only; CJS require will fail.
retinajs as named import
wrong
```
import retinajs from 'retinajs'
```
correct
```
import { retinajs } from 'retinajs'
```
Since v2 the default export is the function itself, but named export also exists. Prefer default for simplicity.
retina (global)
wrong
```
retinajs()
```
correct
```
window.retinajs('img')
```
In browser, the library sets window.retinajs. Call with a selector or element collection.

types

wrong

import { RetinaOptions } from 'retinajs'

correct

import type { RetinaOptions } from 'retinajs'

Type imports are available for TS users; value import will fail at runtime.

Quickstart

Shows how to install, import, and use retinajs to auto-swap images on retina displays.

// Install: npm install retinajs

import retinajs from 'retinajs';

// Option 1: Auto-process all images with data-rjs attribute
document.addEventListener('DOMContentLoaded', () => {
  retinajs();
});

// Option 2: Process specific elements
const images = document.querySelectorAll('img[data-rjs]');
retinajs(images);

// HTML example:
// <img src="normal.png" data-rjs="2" />
// will become <img src="normal@2x.png" /> on retina devices

// For inline backgrounds:
// <div style="background: url(normal.png)" data-rjs="2"></div>