Holder

Holder renders image placeholders in browser using SVG.

Used by thousands of open source projects (including Bootstrap v3) and many other sites.

No extra requests, small bundle size, highly customizable.

Installing

• npm: npm install holderjs
• yarn: yarn add holderjs
• unpkg: https://unpkg.com/holderjs
• cdnjs: https://cdnjs.com/libraries/holder
• jsDelivr: https://www.jsdelivr.com/package/npm/holderjs
• Bower: bower install holderjs
• Rails Assets: gem 'rails-assets-holderjs'
• Meteor: meteor add imsky:holder
• Composer: php composer.phar update imsky/holder
• NuGet: Install-Package Holder.js

Usage

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/300x200">

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

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

Programmatic usage

To programmatically insert a placeholder use the run() API:

var myImage = document.getElementById('myImage');

Holder.run({
  images: myImage
});

Placeholder options

Placeholder options are set through URL properties, e.g. holder.js/300x200?x=y&a=b. Multiple options are separated by the & character.

• theme: The theme to use for the placeholder. Example: holder.js/300x200?theme=sky
• random: Use random theme. Example: holder.js/300x200?random=yes
• bg: Background color. Example: holder.js/300x200?bg=2a2025
• fg: Foreground (text) color. Example: holder.js/300x200?fg=ffffff
• text: Custom text. Example: holder.js/300x200?text=Hello
• size: Custom text size. Defaults to pt units. Example: holder.js/300x200?size=50
• font: Custom text font. Example: holder.js/300x200?font=Helvetica
• align: Custom text alignment (left, right). Example: holder.js/300x200?align=left
• outline: Draw outline and diagonals for placeholder. Example: holder.js/300x200?outline=yes
• lineWrap: Maximum line length to image width ratio. Example: holder.js/300x200?lineWrap=0.5

Themes

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.

Customizing themes

Themes have 5 properties: fg, bg, 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.addTheme("dark", {
  bg: "#000",
  fg: "#aaa",
  size: 11,
  font: "Monaco",
  fontweight: "normal"
});

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.addTheme("thumbnail", { bg: "#fff", text: "Thumbnail" });

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.addTheme("bright", {
  bg: "white", fg: "gray", size: 12
});
script>

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

Holder.addTheme("bright", {bg: "white", fg: "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?theme=simple" id="new">

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

Inserting an image with custom theme

You can add a placeholder programmatically by chaining Holder calls:

Holder.addTheme("new", {
  fg: "#ccc",
  bg: "#000",
  size: 10
}).addImage("holder.js/200x100?theme=new", "body").run();

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

Text

Holder automatically adds line breaks to text that goes outside of the image boundaries. If the text is so long it goes out of both horizontal and vertical boundaries, the text is moved to the top. If you prefer to control the line breaks, you can add \n to the text property:

<img data-src="holder.js/300x200?text=Add \n line breaks \n anywhere.">

If you would like to disable line wrapping, set the nowrap option to true:

<img data-src="holder.js/300x200?text=Add \n line breaks \n anywhere.&nowrap=true">

When using the text option, the image dimesions are not shown. To reinsert the dimension into the text, simple use the special holder_dimensions placeholder.

<img data-src="holder.js/90px80p?theme=sky&text=Placeholder dimensions: holder_dimensions">

Placeholders using a custom font are rendered using canvas by default, due to SVG's constraints on cross-domain resource linking. If you're using only locally available fonts, you can disable this behavior by setting noFontFallback to true in Holder.run options. However, if you need to render a SVG placeholder using an externally loaded font, you have to use the object tag instead of the img tag and add a holderjs class to the appropriate link tags. Here's an example:

<head>
<link href="http://.../font-awesome.css" rel="stylesheet" class="holderjs">
head>
<body>
<object data-src="holder.js/300x200?font=FontAwesome">object>

Important: When testing locally, font URLs must have a http or https protocol defined.

Important: Fonts served from locations other than public registries (i.e. Google Fonts, Typekit, etc.) require the correct CORS headers to be set. See How to use CDN with Webfonts for more details.