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
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
.
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">
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"})
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()
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"
})
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.
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" })
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
.
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
.
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
.
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"})
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.
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.
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})
Holder is compatible with lazyload.js
and works with both fluid and fixed-width images. For best results, run .lazyload({skip_invisible:false})
.
- Chrome
- Firefox 3+
- Safari 4+
- Internet Explorer 6+ (with fallback for older IE)
- Android (with fallback)
Holder is provided under the MIT License.
Holder is a project by Ivan Malopinsky.