thomaswdonnelly/holder

Client-side image placeholders.

Holder

Holder uses SVG and canvas to render image placeholders on the client side.

Bootstrap uses Holder in documentation.

You can install Holder using Bower: bower install holderjs

How to use it

Include holder.js in your HTML:

<script src="holder.js"></script>

Holder will then process all images with a specific src attribute, like this one:

<img src="holder.js/200x300">

The above tag will render as a placeholder 200 pixels wide and 300 pixels tall.

To avoid console 404 errors, you can use data-src instead of src.

Theming

Holder includes support for themes, to help placeholders blend in with your layout.

There are 6 default themes: sky, vine, lava, gray, industrial, and social. Use them like so:

<img src="holder.js/200x300/sky">

Customizing themes

Themes have 5 properties: foreground, background, size, font and fontweight. The size property specifies the minimum font size for the theme. The fontweight default value is bold. You can create a sample theme like this:

Holder.add_theme("dark", {background:"#000", foreground:"#aaa", size:11, font: "Monaco", fontweight:"normal"})

Using custom themes

There are two ways to use custom themes with Holder:

• Include theme at runtime to render placeholders already using the theme name
• Include theme at any point and re-render placeholders that are using the theme name

The first approach is the easiest. After you include holder.js, add a script tag that adds the theme you want:

<script src="holder.js"></script>
<script> Holder.add_theme("bright", { background: "white", foreground: "gray", size: 12 })</script>

The second approach requires that you call run after you add the theme, like this:

Holder.add_theme("bright", { background: "white", foreground: "gray", size: 12}).run()

Using custom themes and domain on specific images

You can use Holder in different areas on different images with custom themes:

<img data-src="example.com/100x100/simple" id="new">

Holder.run({
    domain: "example.com",
    themes: {
        "simple":{
            background:"#fff",
            foreground:"#000",
            size:12
            }
    },
    images: "#new"
    })

Using custom colors on specific images

Custom colors on a specific image can be specified in the background:foreground format using hex notation, like this:

<img data-src="holder.js/100x200/#000:#fff">

The above will render a placeholder with a black background and white text.

Custom text

You can specify custom text using the text: operator:

<img data-src="holder.js/200x200/text:hello world">

If you have a group of placeholders where you'd like to use particular text, you can do so by adding a text property to the theme:

Holder.add_theme("thumbnail", { background: "#fff", text: "Thumbnail" })

Fluid placeholders

Specifying a dimension in percentages creates a fluid placeholder that responds to media queries.

<img data-src="holder.js/100%x75/social">

By default, the fluid placeholder will show its current size in pixels. To display the original dimensions, i.e. 100%x75, set the textmode flag to literal like so: holder.js/100%x75/textmode:literal.

Automatically sized placeholders

If you'd like to avoid Holder enforcing an image size, use the auto flag like so:

<img data-src="holder.js/200x200/auto">

The above will render a placeholder without any embedded CSS for height or width.

To show the current size of an automatically sized placeholder, set the textmode flag to exact like so: holder.js/200x200/auto/textmode:exact.

Background placeholders

Holder can render placeholders as background images for elements with the holderjs class, like this:

#sample {background:url(?holder.js/200x200/social) no-repeat}

<div id="sample" class="holderjs"></div>

The Holder URL in CSS should have a ? in front. You can change the default class by specifying a selector as the bgnodes property when calling Holder.run.

Customizing only the settings you need

Holder extends its default settings with the settings you provide, so you only have to include those settings you want changed. For example, you can run Holder on a specific domain like this:

Holder.run({domain:"example.com"})

Using custom settings on load

You can prevent Holder from running its default configuration by executing Holder.run with your custom settings right after including holder.js. However, you'll have to execute Holder.run again to render any placeholders that use the default configuration.

Inserting an image with optional custom theme

You can add a placeholder programmatically by chaining Holder calls:

Holder.add_theme("new",{foreground:"#ccc", background:"#000", size:10}).add_image("holder.js/200x100/new", "body").run()

The first argument in add_image is the src attribute, and the second is a CSS selector of the parent element.

Changing rendering engine

By default, Holder renders placeholders using SVG, however it has a fallback canvas engine that it uses in case the browser lacks SVG support. If you'd like to force canvas rendering, you can do it like so:

Holder.run({use_canvas:true})

Using with lazyload.js

Holder is compatible with lazyload.js and works with both fluid and fixed-width images. For best results, run .lazyload({skip_invisible:false}).

Browser support

• Chrome
• Firefox 3+
• Safari 4+
• Internet Explorer 6+ (with fallback for older IE)
• Android (with fallback)

License

Holder is provided under the MIT License.

Credits

Holder is a project by Ivan Malopinsky.