Need help with holder?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

imsky
5.7K Stars 600 Forks MIT License 509 Commits 29 Opened issues

Description

:city_sunrise: Client-side image placeholders.

Services available

!
?

Need anything else?

Contributors list

No Data

Holder

Holder renders image placeholders on the client side using SVG.

Used by Bootstrap, thousands of open source projects, and many other sites.

npm Travis Build Status Package Quality NerdyData Popularity jsDelivr Hits

Installing

Usage

Include

holder.js
in your HTML:

Holder will then process all images with a specific

src
attribute, like this one:

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:

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:


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:

If you would like to disable line wrapping, set the

nowrap
option to
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.

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:

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.

 placeholders work like 
placeholders, with the added benefit of their DOM being able to be inspected and modified. As with
placeholders, the
data-src
attribute is more reliable than the
data
attribute.

Fluid placeholders

Important: Percentages are specified with the

p
character, not with the
%
character.

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


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/100px75?textmode=literal
.

Automatically sized placeholders

If you'd like to avoid Holder enforcing an image size, use the

auto
flag like so:

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=yes&textmode=exact
.

Preventing updates on window resize

Both fluid placeholders and automatically sized placeholders in exact mode are updated when the window is resized. To set whether or not a particular image is updated on window resize, you can use the

setResizeUpdate
method like so:
var img = $('#placeholder').get(0);
Holder.setResizeUpdate(img, false);

The above will pause any render updates on the specified image (which must be a DOM object).

To enable updates again, run the following:

Holder.setResizeUpdate(img, true);

This will enable updates and immediately render the placeholder.

Background placeholders

Holder can render placeholders as background images for elements with the

holderjs
class, like this:
#sample {background:url(?holder.js/200x200?theme=social) no-repeat}

The Holder URL in CSS should have a

?
in front. Like in image placeholders, you can specify the Holder URL in a
data-background-src
attribute:

Important: Make sure to define a height and/or width for elements with background placeholders. Fluid background placeholders are not yet supported.

Runtime settings

Holder provides several options at runtime that affect the process of image generation. These are passed in through

Holder.run
calls.
  • domain
    : The domain to use for image generation. Default value:
    holder.js
    .
  • dataAttr
    : The HTML attribute used to define a fallback to the native
    src
    attribute. Default value:
    data-src
    .
  • renderer
    : The renderer to use. Options available:
    svg
    ,
    canvas
    . Default value:
    svg
    .
  • images
    : The CSS selector used for finding
    img
    tags. Default value:
    img
    .
  • objects
    : The CSS selector used for finding
    object
    placeholders. Default value:
    object
    .
  • bgnodes
    : The CSS selector used for finding elements that have background palceholders. Default value:
    body .holderjs
    .
  • stylenodes
    : The CSS selector used for finding stylesheets to import into SVG placeholders. Default value:
    head link.holderjs
    .
  • noFontFallback
    : Do not fall back to canvas if using custom fonts.
  • noBackgroundSize
    : Do not set
    background-size
    for background placeholders.

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.

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})
.

Using with Vue

You can use Holder in Vue 2+ projects with vue-holderjs.

Using with Angular.js

You can use Holder in Angular projects with ng-holder or with angular-2-holderjs for Angular 2 projects.

Using with Meteor

Because Meteor includes scripts at the top of the document by default, the DOM may not be fully available when Holder is called. For this reason, place Holder-related code in a "DOM ready" event listener.

Using with Webpack

If you're using

ProvidePlugin
in your Webpack config, make sure to configure it as follows:
plugins: [
  new webpack.ProvidePlugin({
    'Holder': 'holderjs',
    'holder': 'holderjs',
    'window.Holder': 'holderjs'
  })
]

Browser support

  • Chrome
  • Firefox 3+
  • Safari 4+
  • Internet Explorer 9+ (with partial support for 6-8)
  • Opera 12+
  • Android (with fallback)

Source

License

Holder is provided under the MIT License.

Credits

Holder is a project by Ivan Malopinsky.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.