JavaScript library v0.46.3

Lazy-loading responsive images. Our JavaScript SDK library does all the heavy lifting for you. Works in browsers and Node.js. Open source and test suite on Github.

Installation

Browser

Use our CDN for a fast-loading and always up-to-date library. Insert this line above the closing </body> tag in your HTML. It's 83 kB (24 kB gzipped).

<script src="https://tiny.pictures/tiny.pictures.min.js"></script>

This file will expose the library class as the global variable TinyPictures.

Node.js

npm install --save tiny.pictures-js

Just add var TinyPictures = require('tiny.pictures-js') to your code and use the factory class in the TinyPictures variable.

Demo

Start a local demo server with the following command:

npm run demo

Then point your browser to http://localhost:3000/ to see the SDK's functions in action.

Usage

Once the class is loaded and stored in a variable, you can instantiate it by supplying an options object.

var tinyPictures = new TinyPictures(options)

Example

var tinyPictures = new TinyPictures({
    // document and location is only necessary when run in a browser
    document: window.document,
    location: window.location,
    user: 'demo',
    protocol: 'http'
})

Options

document (Document)
Mandatory when used in a browser. The window.document object.
location (Location)
Mandatory when used in a browser. The window.location object.
user (string)
Mandatory. Your tiny.pictures user name.
overrideSourcesImages ([string]|string|boolean)
Optional. Default []. Use this to supply a set of replacement images that are used instead of images from non-public hosts such as localhost during development. Can be an array of publicly available image URLs, a string that specifies the desired type of image ('random', 'abstract', 'animals', 'business', 'cats', 'city', 'food', 'nightlife', 'fashion', 'people', 'nature', 'sports', 'technics', or 'transport'), or a boolean (true for 'random' and false for []).
overrideSourcesAlways (boolean)
Optional. Default false. Set to true to always replace the original source images by overrideSourcesImages, even if they were publicly available.

While being very useful and funny during development, this may have a serious impact on your employment status if used in production. Use with caution!

protocol ('https'|'http')
Optional. Default 'https'. Set to 'http' if you are running a non-TLS-encrypted website to save your users' devices from unnecessary computation time.
defaultBaseUrl (string)
Optional. Default ''. This value is used by the url function as the default baseUrl parameter.
namedSources ({name: string, url: string}[])
Optional. Default []. An array of objects describing the named sources you configured on your dashboard. Copy the array directly from there. If a source image URL starts with one of your named sources, you'll get a prettier tiny.pictures URL (e. g. https://api.tiny.pictures/demo/main/example1.jpg).
srcsetWidths ([int])
Optional. Default is a quite long list of image widths. This list is used whenever an img tag's srcset attribute is created.

API

url

This function converts any image URL to a tiny.pictures URL. You can specify image processing operations in the options object.

Function parameters

url (string)
URL of the original image.
options (object)
Optional. Default {}. Object containing the image processing options you'd like to be applied.
slashesDenoteHost (boolean)
Optional. Default false. If the url portion between a leading // and the next / should be treated as a host. Set to true if url is in format //your.domain/path/to/image.jpg. Omit or set to false if url is in format //path/to/image.jpg or includes a protocol.
baseUrl (string)
Optional. No default. Base url that url gets resolved against, if url is a relative URL. Throws an error if not set and url is relative. Is set to to the current page's URL (location.href) automatically in the browser.

Function returns

string

Examples

url('http://your.domain/path/to/image.jpg')
// 'https://tiny.pictures/api/demo/?source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg'

url('http://your.domain/path/to/image.jpg', {width: 200})
// 'https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg'

// In the browser when on page http://your.domain/path/index.html:
url('image.jpg', {width: 200})
// https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fimage.jpg

url('//path/to/image.jpg', {width: 200})
// https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg

url('//your.domain/path/to/image.jpg', {width: 200}, true)
// https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg

// In Node.js:
url('image.jpg', {width: 200})
// throws error

url('image.jpg', {width: 200}, null, 'http://your.domain/path/index.html')
// https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fimage.jpg

immediate

This function automatically replaces image URLs of img tags to tiny.pictures URLs. You can use and combine any image processing operation you like. If you specify the source image's width, we automatically calculate a srcset attribute that enables the browser to decide which image size to load for an optimal user experience on your website. Since tiny.pictures makes use of progressive image formats (progressive operation), the browser is able to render images while they are still loading. Please also consider using this function via our jQuery plugin for convenience.

Function parameters

img (DOM node)
Native DOM node of the image.
options (object)
Options object specifying the image processing operations you'd like to be performed that will be passed to the url function.

Function returns

undefined

img tag attributes

data-src (string)
URL of the original image. It gets transformed into a tiny.pictures URL and put into the src attribute.
src (string)
Optional. No default. Fallback URL of the original image that is only used if data-src is not set.
data-tiny.pictures (JSON)
Optional. No default. JSON representation of an options object specifying the operations you'd like to apply. For example, to resize the image to a width of 200 pixels and flip the image, use data-tiny.pictures='{"width": 200, "flip": true}'.
data-tiny.pictures-width (number)
Optional. No default. The original image's width in pixels. If set, a srcset attribute with a set of tiny.pictures URLs with different widths is calculated and put into the srcset attribute as soon as the user is about to scroll the image into view. For example, to tell the library that the original image is 1000 pixels wide, use data-tiny.pictures-width=1000. Do not set a srcset yourself when using this feature.

If neither the data-tiny.pictures nor the data-tiny.pictures-width attribute is set, the original source image URL is used for showing the image.

Examples

<img data-src="http://your.domain/path/to/image.jpg">
<!-- Original source image url is used -->
<!-- src="http://your.domain/path/to/image.jpg" -->

<img data-src="http://your.domain/path/to/image.jpg" data-tiny.pictures='{"width":200}'>
<!-- tiny.pictures url is used -->
<!-- src="https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg" -->

<img data-src="http://your.domain/path/to/image.jpg" data-tiny.pictures-width=330>
<!-- tiny.pictures url source set is used -->
<!-- The browser decides which file to load based on the user's viewport width and display density -->
<!-- srcset="https://tiny.pictures/api/demo/?width=10&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 10w, https://tiny.pictures/api/demo/?width=25&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 25w, https://tiny.pictures/api/demo/?width=50&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 50w, https://tiny.pictures/api/demo/?width=100&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 100w, https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 200w, https://tiny.pictures/api/demo/?width=300&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 300w, https://tiny.pictures/api/demo/?width=330&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 330w" -->

<script src="https://tiny.pictures/tiny.pictures.min.js"></script>
<script>
    var tinyPictures = new TinyPictures({
        document: window.document,
        location: window.location,
        user: 'demo'
    })
    var list = document.getElementsByTagName('img')
    for (var i = 0; i < list.length; i++) {
        tinyPictures.immediate(list[i])
    }
</script>

Benefits

The following image is loaded with

<img data-src="https://tiny.pictures/example1.jpg" data-tiny.pictures-width=1000>

Depending on the user's viewport and display density, the browser loads different images for the fastest possible load time and best user experience. Notice that mobile users may save up to 94.4 % bandwidth in this example.

URLSize
/?width=200&source=...8.5 kB
/?width=300&source=...16.7 kB
/?width=400&source=...27.6 kB
/?width=500&source=...42.2 kB
/?width=600&source=...57.9 kB
/?width=700&source=...78.2 kB
/?width=800&source=...98.7 kB
/?width=900&source=...122.0 kB
/?width=1000&source=...151.0 kB

For detailed insights into responsive images and why you should also use the sizes attribute, read Jason Grigsby's excellent Responsive Images 101 Series or the illustrative Srcset and sizes by Eric Portis.

immediateAll

This is a convenience function to execute immediate on all img tags.

Function parameters

None

Function returns

undefined

lazyload

This function does the same as the immediateAll function except that it defers image loading to when the user actually scrolls down to them. It sets the images' src attribute as soon as the user is about to scroll the image into view (300 pixels above).

Function parameters

None

Function returns

undefined

Examples

<img data-src="http://your.domain/path/to/image.jpg">
<!-- Original source image url is used for lazy loading -->
<!-- src="http://your.domain/path/to/image.jpg" -->

<img data-src="http://your.domain/path/to/image.jpg" data-tiny.pictures='{"width":200}'>
<!-- tiny.pictures url is used for lazy loading -->
<!-- src="https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg" -->

<img data-src="http://your.domain/path/to/image.jpg" data-tiny.pictures-width=330>
<!-- tiny.pictures url source set is used for lazy loading -->
<!-- The browser decides which file to load based on the user's viewport width and display density -->
<!-- srcset="https://tiny.pictures/api/demo/?width=10&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 10w, https://tiny.pictures/api/demo/?width=25&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 25w, https://tiny.pictures/api/demo/?width=50&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 50w, https://tiny.pictures/api/demo/?width=100&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 100w, https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 200w, https://tiny.pictures/api/demo/?width=300&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 300w, https://tiny.pictures/api/demo/?width=330&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg 330w" -->

<script src="https://tiny.pictures/tiny.pictures.min.js"></script>
<script>
    var tinyPictures = new TinyPictures({
        document: window.document,
        location: window.location,
        user: 'demo'
    })
    tinyPictures.lazyload()
</script>

jQuery

You may register tiny.pictures as a jQuery plugin. This creates a tinyPictures function, that executes the immediate function for all matching DOM nodes. The only parameter of this function will be passed to immediate and – ultimately – to url as the options parameter.

Example

<img data-src="http://your.domain/path/to/image.jpg">
<!-- src="https://tiny.pictures/api/demo/?width=200&source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg" -->
<script src="jQuery.js"></script>
<script src="https://tiny.pictures/tiny.pictures.min.js"></script>
<script>
    var tinyPictures = new TinyPictures({
        document: window.document,
        location: window.location,
        user: 'demo'
    })
    tinyPictures.registerJQueryPlugin($)
    $('img').tinyPictures({"width":200})
</script>

AngularJS (a.k.a. Angular 1)

If the SDK is loaded after AngularJS, it automatically registers a tiny.pictures module and a filter called tinyPicturesUrl, that exposes the url function for use in templates.

Example

<script src="angular.js"></script>
<script src="https://tiny.pictures/tiny.pictures.min.js"></script>
<script>
    var tinyPictures = new TinyPictures({
        document: window.document,
        location: window.location,
        user: 'demo'
    })
    tinyPictures.registerAngularJsModule(angular)
    angular.module('yourApp', ['tiny.pictures'])
</script>
…
<img ng-src="{{ item.imageUrl | tinyPicturesUrl: {width: 200, quality: settings.imageQuality} }}">

Angular (a.k.a. Angular 2)

With Angular 2 and above, you may just import the library in your component files and use its functions directly. The example below also shows a simple pipe based on the url function.

Example

import { Component, Pipe, PipeTransform } from '@angular/core'
import TinyPictures from 'tiny.pictures-js/browser'

const imageUrl = 'https://tiny.pictures/example1.jpg'
const tinyPictures = new TinyPictures({
    document: window.document,
    location: window.location,
    user: 'demo'
})

@Component({
    selector: 'my-component',
    template: '<h1>Nice images</h1>' +
              '<img src="' + tinyPictures.url(imageUrl) + '">' +
              '<img src="imageUrl | tinyPicturesUrl">'
})
export class MyComponent {
    imageUrl: string = imageUrl
}

@Pipe({
    name: 'tinyPicturesUrl'
})
export class TinyPicturesUrlPipe implements PipeTransform {
    transform(...args): string {
        return tinyPictures.url(...args)
    }
 }