{"id":13426669,"url":"https://github.com/imsky/holder","last_synced_at":"2025-05-13T16:07:02.794Z","repository":{"id":3578820,"uuid":"4641606","full_name":"imsky/holder","owner":"imsky","description":":city_sunrise: Client-side image placeholders.","archived":false,"fork":false,"pushed_at":"2023-10-07T03:19:47.000Z","size":1556,"stargazers_count":5834,"open_issues_count":31,"forks_count":592,"subscribers_count":205,"default_branch":"master","last_synced_at":"2025-05-10T16:01:47.444Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"http://holderjs.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-06-12T19:00:26.000Z","updated_at":"2025-04-29T15:37:33.000Z","dependencies_parsed_at":"2022-07-21T21:47:39.907Z","dependency_job_id":"83f12af3-bef0-4b47-be31-fb2295406e70","html_url":"https://github.com/imsky/holder","commit_stats":{"total_commits":463,"total_committers":42,"mean_commits":"11.023809523809524","dds":"0.36717062634989206","last_synced_commit":"178166049c8ff03847b687a99d533e8efa92f08d"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fholder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fholder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fholder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fholder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imsky","download_url":"https://codeload.github.com/imsky/holder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253967987,"owners_count":21992252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-07-31T00:01:40.683Z","updated_at":"2025-05-13T16:07:02.748Z","avatar_url":"https://github.com/imsky.png","language":"JavaScript","readme":"# Holder\n\n![](http://imsky.github.io/holder/images/header.png)\n\nHolder renders image placeholders in browser using SVG.\n\nUsed by thousands of [open source projects](https://github.com/search?q=holder.js+in%3Apath\u0026type=Code\u0026ref=searchresults) (including [Bootstrap v3](https://getbootstrap.com)) and [many](https://nerdydata.com/technology-reports/Holder.js/1cf03fe7-0e02-40ef-be69-f00ca9547fc9) [other](http://libscore.com/#Holder) sites.\n\nNo extra requests, small bundle size, highly customizable.\n\n[![npm](https://img.shields.io/npm/v/holderjs.svg)](https://www.npmjs.com/package/holderjs)\n[![Travis Build Status](https://img.shields.io/travis/imsky/holder.svg)](https://travis-ci.org/imsky/holder)\n[![Package Quality](http://npm.packagequality.com/shield/holderjs.svg)](http://packagequality.com/#?package=holderjs)\n[![NerdyData Popularity](https://badges.nerdydata.com/1cf03fe7-0e02-40ef-be69-f00ca9547fc9)](https://nerdydata.com/technology-reports/Holder.js/1cf03fe7-0e02-40ef-be69-f00ca9547fc9)\n[![jsDelivr Hits](https://data.jsdelivr.com/v1/package/npm/holderjs/badge?style=rounded)](https://www.jsdelivr.com/package/npm/holderjs)\n\n## Installing\n\n* [npm](https://npmjs.com/): `npm install holderjs`\n* [yarn](https://yarnpkg.com/): `yarn add holderjs`\n* [unpkg](https://unpkg.com/): \u003chttps://unpkg.com/holderjs\u003e\n* [cdnjs](http://cdnjs.com/): \u003chttps://cdnjs.com/libraries/holder\u003e\n* [jsDelivr](https://www.jsdelivr.com): \u003chttps://www.jsdelivr.com/package/npm/holderjs\u003e\n* [Bower](https://bower.io/): `bower install holderjs`\n* [Rails Assets](https://rails-assets.org): `gem 'rails-assets-holderjs'`\n* [Meteor](https://atmospherejs.com/): `meteor add imsky:holder`\n* [Composer](https://packagist.org/): `php composer.phar update imsky/holder`\n* [NuGet](https://www.nuget.org/): `Install-Package Holder.js`\n\n## Usage\n\nInclude ``holder.js`` in your HTML:\n\n```html\n\u003cscript src=\"holder.js\"\u003e\u003c/script\u003e\n```\n\nHolder will then process all images with a specific ``src`` attribute, like this one:\n\n```html\n\u003cimg src=\"holder.js/300x200\"\u003e\n```\n\nThe above tag will render as a placeholder 300 pixels wide and 200 pixels tall.\n\nTo avoid console 404 errors, you can use ``data-src`` instead of ``src``.\n\n### Programmatic usage\n\nTo programmatically insert a placeholder use the `run()` API:\n\n```js\nvar myImage = document.getElementById('myImage');\n\nHolder.run({\n  images: myImage\n});\n```\n\n## Placeholder options\n\nPlaceholder options are set through URL properties, e.g. `holder.js/300x200?x=y\u0026a=b`. Multiple options are separated by the `\u0026` character.\n\n* `theme`: The theme to use for the placeholder. Example: `holder.js/300x200?theme=sky`\n* `random`: Use random theme. Example: `holder.js/300x200?random=yes`\n* `bg`: Background color. Example: `holder.js/300x200?bg=2a2025`\n* `fg`: Foreground (text) color. Example: `holder.js/300x200?fg=ffffff`\n* `text`: Custom text. Example: `holder.js/300x200?text=Hello`\n* `size`: Custom text size. Defaults to `pt` units. Example: `holder.js/300x200?size=50`\n* `font`: Custom text font. Example: `holder.js/300x200?font=Helvetica`\n* `align`: Custom text alignment (left, right). Example: `holder.js/300x200?align=left`\n* `outline`: Draw outline and diagonals for placeholder. Example: `holder.js/300x200?outline=yes`\n* `lineWrap`: Maximum line length to image width ratio. Example: `holder.js/300x200?lineWrap=0.5`\n\n### Themes\n\n![](http://imsky.github.io/holder/images/holder_sky.png)![](http://imsky.github.io/holder/images/holder_vine.png)![](http://imsky.github.io/holder/images/holder_lava.png)\n\nHolder includes support for themes, to help placeholders blend in with your layout.\n\nThere are 6 default themes: ``sky``, ``vine``, ``lava``, ``gray``, ``industrial``, and ``social``.\n\n#### Customizing themes\n\nThemes 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:\n\n```js\nHolder.addTheme(\"dark\", {\n  bg: \"#000\",\n  fg: \"#aaa\",\n  size: 11,\n  font: \"Monaco\",\n  fontweight: \"normal\"\n});\n```\n\nIf 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:\n\n```js\nHolder.addTheme(\"thumbnail\", { bg: \"#fff\", text: \"Thumbnail\" });\n```\n\n#### Using custom themes\n\nThere are two ways to use custom themes with Holder:\n\n* Include theme at runtime to render placeholders already using the theme name\n* Include theme at any point and re-render placeholders that are using the theme name\n\nThe first approach is the easiest. After you include ``holder.js``, add a ``script`` tag that adds the theme you want:\n\n```html\n\u003cscript src=\"holder.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nHolder.addTheme(\"bright\", {\n  bg: \"white\", fg: \"gray\", size: 12\n});\n\u003c/script\u003e\n```\n\nThe second approach requires that you call ``run`` after you add the theme, like this:\n\n```js\nHolder.addTheme(\"bright\", {bg: \"white\", fg: \"gray\", size: 12}).run();\n```\n\n#### Using custom themes and domain on specific images\n\nYou can use Holder in different areas on different images with custom themes:\n\n```html\n\u003cimg data-src=\"example.com/100x100?theme=simple\" id=\"new\"\u003e\n```\n\n```js\nHolder.run({\n  domain: \"example.com\",\n  themes: {\n    \"simple\": {\n      bg: \"#fff\",\n      fg: \"#000\",\n      size: 12\n    }\n  },\n  images: \"#new\"\n});\n```\n\n#### Inserting an image with custom theme\n\nYou can add a placeholder programmatically by chaining Holder calls:\n\n```js\nHolder.addTheme(\"new\", {\n  fg: \"#ccc\",\n  bg: \"#000\",\n  size: 10\n}).addImage(\"holder.js/200x100?theme=new\", \"body\").run();\n```\n\nThe first argument in ``addImage`` is the ``src`` attribute, and the second is a CSS selector of the parent element.\n\n### Text\n\nHolder 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:\n\n```html\n\u003cimg data-src=\"holder.js/300x200?text=Add \\n line breaks \\n anywhere.\"\u003e\n``````\n\nIf you would like to disable line wrapping, set the `nowrap` option to `true`:\n\n```html\n\u003cimg data-src=\"holder.js/300x200?text=Add \\n line breaks \\n anywhere.\u0026amp;nowrap=true\"\u003e\n```\n\nWhen using the `text` option, the image dimesions are not shown. To reinsert the dimension into the text, simple use the special `holder_dimensions` placeholder.\n\n```html\n\u003cimg data-src=\"holder.js/90px80p?theme=sky\u0026text=Placeholder dimensions: holder_dimensions\"\u003e\n```\n\nPlaceholders 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:\n\n```html\n\u003chead\u003e\n\u003clink href=\"http://.../font-awesome.css\" rel=\"stylesheet\" class=\"holderjs\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cobject data-src=\"holder.js/300x200?font=FontAwesome\"\u003e\u003c/object\u003e\n```\n\n**Important:** When testing locally, font URLs must have a `http` or `https` protocol defined.\n\n**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](https://www.maxcdn.com/one/tutorial/how-to-use-cdn-with-webfonts/) for more details.\n\n`\u003cobject\u003e` placeholders work like `\u003cimg\u003e` placeholders, with the added benefit of their DOM being able to be inspected and modified. As with `\u003cimg\u003e` placeholders, the `data-src` attribute is more reliable than the `data` attribute.\n\n### Fluid placeholders\n\n**Important:** Percentages are specified with the `p` character, not with the `%` character.\n\nSpecifying a dimension in percentages creates a fluid placeholder that responds to media queries.\n\n```html\n\u003cimg data-src=\"holder.js/100px75?theme=social\"\u003e\n```\n\nBy 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`.\n\n### Automatically sized placeholders\n\nIf you'd like to avoid Holder enforcing an image size, use the ``auto`` flag like so:\n\n```html\n\u003cimg data-src=\"holder.js/200x200?auto=yes\"\u003e\n```\n\nThe above will render a placeholder without any embedded CSS for height or width.\n\nTo show the current size of an automatically sized placeholder, set the ``textmode`` flag to ``exact`` like so: `holder.js/200x200?auto=yes\u0026textmode=exact`.\n\n### Preventing updates on window resize\n\nBoth 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:\n\n```js\nvar img = $('#placeholder').get(0);\nHolder.setResizeUpdate(img, false);\n```\n\nThe above will pause any render updates on the specified image (which must be a DOM object).\n\nTo enable updates again, run the following:\n\n```js\nHolder.setResizeUpdate(img, true);\n```\n\nThis will enable updates and immediately render the placeholder.\n\n### Background placeholders\n\nHolder can render placeholders as background images for elements with the `holderjs` class, like this:\n\n```css\n#sample {background:url(?holder.js/200x200?theme=social) no-repeat}\n```\n\n```html\n\u003cdiv id=\"sample\" class=\"holderjs\"\u003e\u003c/div\u003e\n```\n\nThe 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:\n\n```html\n\u003cdiv class=\"holderjs\" data-background-src=\"?holder.js/300x200\"\u003e\u003c/div\u003e\n```\n\n**Important:** Make sure to define a height and/or width for elements with background placeholders. Fluid background placeholders are not yet supported.\n\n## Runtime settings\n\nHolder provides several options at runtime that affect the process of image generation. These are passed in through `Holder.run` calls.\n\n* `domain`: The domain to use for image generation. Default value: `holder.js`.\n* `dataAttr`: The HTML attribute used to define a fallback to the native `src` attribute. Default value: `data-src`.\n* `renderer`: The renderer to use. Options available: `svg`, `canvas`. Default value: `svg`.\n* `images`: The CSS selector used for finding `img` tags. Default value: `img`.\n* `objects`: The CSS selector used for finding `object` placeholders. Default value: `object`.\n* `bgnodes`: The CSS selector used for finding elements that have background palceholders. Default value: `body .holderjs`.\n* `stylenodes`: The CSS selector used for finding stylesheets to import into SVG placeholders. Default value: `head link.holderjs`.\n* `noFontFallback`: Do not fall back to canvas if using custom fonts.\n* `noBackgroundSize`: Do not set `background-size` for background placeholders.\n\n### Using custom settings on load\n\nYou 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.\n\n## Using with [lazyload.js](https://github.com/tuupola/jquery_lazyload)\n\n\nHolder is compatible with ``lazyload.js`` and works with both fluid and fixed-width images. For best results, run `.lazyload({skip_invisible:false})`.\n\n## Using with React\n\nWhen using Holder in a React component, execute `Holder.run` in `componentDidMount` to enable rendering after state changes. See [this issue](https://github.com/imsky/holder/issues/225) for more details.\n\n## Using with Vue\n\nYou can use Holder in Vue 2+ projects with [vue-holderjs](https://github.com/boogermann/vue-holderjs).\n\n## Using with Angular.js\n\nYou can use Holder in Angular projects with [ng-holder](https://github.com/joshvillbrandt/ng-holder) or with [angular-2-holderjs](https://github.com/aogriffiths/angular-2-holderjs) for Angular 2 projects.\n\n## Using with Meteor\n\nBecause 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.\n\n## Using with Webpack\n\nIf you're using `ProvidePlugin` in your Webpack config, make sure to configure it as follows:\n\n```js\nplugins: [\n  new webpack.ProvidePlugin({\n    'Holder': 'holderjs',\n    'holder': 'holderjs',\n    'window.Holder': 'holderjs'\n  })\n]\n```\n\n## Browser support\n\n* Chrome\n* Firefox 3+\n* Safari 4+\n* Internet Explorer 9+ (with partial support for 6-8)\n* Opera 12+\n* Android (with fallback)\n\n## Source\n\n* GitHub: \u003chttps://github.com/imsky/holder\u003e\n* GitLab: \u003chttps://gitlab.com/imsky/holder\u003e\n\n## License\n\nHolder is provided under the [MIT License](http://opensource.org/licenses/MIT).\n\n## Credits\n\nHolder is a project by [Ivan Malopinsky](http://imsky.co).\n","funding_links":[],"categories":["JavaScript","hacktoberfest","Javascript","13. 页面交互","Multimedia"],"sub_categories":["13.4 图片轮播(幻灯片)/图片展示  ###","Image","13.4 图片轮播(幻灯片)/图片展示"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsky%2Fholder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimsky%2Fholder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsky%2Fholder/lists"}