---
{
	"title": "Background image",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "Apply a background image from the given URL in parameter or as per the srcset information.",
	"altLangPrefix": "bgimg",
	"dateModified": "2020-12-09"
}
---
<div class="wb-prettify all-pre hide"></div>

<h2>Purpose</h2>
<p>Apply a background image from the given URL in parameter or as per the srcset information.</p>

<h2>Use when</h2>
<ul>
	<li>Display a decorative background image</li>
</ul>

<h2>Guidance for publisher</h2>
<ul>
	<li>Ensure the text contrast remains valid in the case where the image doesn't load or takes time to load</li>
	<li>Ensure the image is purely decorative, if not, you can alternatively use the Data Picture plugin</li>
</ul>

<h2>Working example</h2>
<ul>
	<li><a href="../../../demos/bgimg/bgimg-en.html">English example</a></li>
	<li><a href="../../../demos/bgimg/bgimg-fr.html">French example</a></li>
</ul>

<h2>Evaluation and report</h2>
<p>There is no evaluation and report available for this component.</p>

<h2>API (Version 1.0)</h2>
<dl class="dl-horizontal">
	<dt>Function</dt>
	<dd>Version 1.0</dd>
	<dt>Configuration</dt>
	<dd>Version 1.0</dd>
	<dt>User interface (Template)</dt>
	<dd>Version 1.0</dd>
	<dt>Data source</dt>
	<dd>Not applicable</dd>
	<dt>View and style</dt>
	<dd>Not applicable</dd>
	<dt>i18n string</dt>
	<dd>Not applicable</dd>
</dl>

<h3>Function</h3>
<p>(Version 1.0)</p>
<table class="table">
	<tr>
		<th>Function type</th>
		<th>Name</th>
		<th>How to implement</th>
		<th>What it does</th>
	</tr>
	<tr>
		<td>jQuery Event</td>
		<td><code>wb-init.wb-bgimg</code></td>
		<td>Triggered manually (e.g., <code>$( ".wb-bgimg" ).trigger( "wb-init.wb-bgimg" );</code>).</td>
		<td>Initializes the bg-img plugin. This plugin will be initialized automatically unless the <code>.wb-bgimg</code> element is added after the page load and wet-boew was initialized.</td>
	</tr>
	<tr>
		<td>jQuery Event</td>
		<td><code>wb-ready.wb-bgimg</code></td>
		<td>Triggered automatically after the plugin initializes.</td>
		<td>Used to identify when and where the plugin initializes (target of the event).
			<pre><code>$( document ).on( "wb-ready.wb-bgimg", ".wb-bgimg", function( event ) {
});</code></pre>
			<pre><code>$elm.on( "wb-ready.wb-bgimg", function( event ) {
});</code></pre>
		</td>
	</tr>
</table>

<h3>Configuration</h3>
<p>(Version 1.0)</p>
<table class="table">
	<tr>
		<th>Option</th>
		<th>Description</th>
		<th>How to configure</th>
		<th>Values</th>
	</tr>
	<tr>
		<td><code>[data-bgimg]</code> String</td>
		<td>Address of the <a href="https://html.spec.whatwg.org/multipage/links.html#hyperlink">hyperlinks</a></td>
		<td>Sets the background image URL to specified.</td>
		<td>Valid URL pointing to a valid image ressource</td>
	</tr>
	<tr>
		<td><code>[data-bgimg-srcset]</code> String</td>
		<td>Images to use in different situations, limited to images sizes for different situations.</td>
		<td>Set a valid <a href="https://html.spec.whatwg.org/multipage/images.html#image-candidate-string">image candidate string</a>.</td>
		<td><code>[ &lt;source-size-value&gt;# , ]? &lt;source-size-value&gt;</code></td>
	</tr>
</table>

<h3>User interface (Template)</h3>
<p>(Version 1.0)</p>
<ul>
	<li>
		<p>Attribute:</p>
		<pre><code>data-bgimg</code></pre>
	</li>
	<li>
		<p>Attribute:</p>
		<pre><code>data-bgimg-srcset</code></pre>
	</li>
</ul>

<h2>Source code</h2>
<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/bgimg">Background image source code on GitHub</a></p>
