retinajs

library2.1.3jsnpmunverified

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.

web-framework

npm install retinajs

github ↗package ↗

INSTALL

IMPORT

SIG · RETINAJS

retinajs

web-frameworkjavascriptv2.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (retinajs function)

✓ import retinajs from 'retinajs'

✗ const retinajs = require('retinajs')

v2 is ESM only; CJS require will fail.

retinajs as named import

✓ import { retinajs } from 'retinajs'

✗ import retinajs from 'retinajs'

Since v2 the default export is the function itself, but named export also exists. Prefer default for simplicity.

retina (global)

✓ window.retinajs('img')

✗ retinajs()

In browser, the library sets window.retinajs. Call with a selector or element collection.

types

✓ import type { RetinaOptions } from 'retinajs'

✗ import { RetinaOptions } from 'retinajs'

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

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>

Debug

Known issues

breakingv2.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`.

affects: >=2.0.0

breakingIn 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.

affects: >=2.0.0

deprecatedThe `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.

affects: >=2.0.0

gotchaIf 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.

affects: >=2.0.0 <2.1.0

gotchaThe 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.

affects: all

Errors

Common errors & fixes

Uncaught TypeError: retinajs is not a function

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

fix

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

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

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.

retinajs is not defined

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.

Cannot read property 'src' of null

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

fix

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

Upgrade

Version history

2.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/strues/retinajs ↗

packagehttps://www.npmjs.com/package/retinajs ↗