How to install Piio Images on any website

Following this guide, you will be able to successfully optimize and deliver all your website images using Piio Images.

Get your Domain Key
Include Piio Images script
Get your images to work
Using Piio Images as background images
Art Direction
Video Posters

1. Get your Domain Key#

The Piio Images library uses a Domain Key to identify your website and where the images are hosted. If you haven't created an account and added your first domain, follow the steps after signing up for a free account here.

2. Include Piio Images script#

Copy and paste the following code inside your <head> and before initializing any other script. This placement is because your images are mission-critical, and this code will be responsible for loading them properly.

Replace the DOMAIN-KEY in the code with the one provided for your domain on the Piio Dashboard.

<script type="text/javascript">
(function(i,m,a,g,e) {
    e = i.getElementsByTagName(m)[0], (g = i.createElement(m)).src = "//pcdn.piiojs.com/"+a+"/image.min.js",
    g.onerror = function() {
        (g = i.createElement(m)).src = "https://fs.piio.co/image-failover.min.js",
        e.parentNode.insertBefore(g, e);
    }, e.parentNode.insertBefore(g, e);
}(document, "script", "DOMAIN-KEY"));
</script>

Preload & preconnect#

Add the following code right after the <head> opening tag and replace the DOMAIN-KEY with the one provided for your domain on the [Piio Dashboard].

<link rel="preconnect" href="//pcdn.piiojs.com">
<link rel="preload" as="script" href="//pcdn.piiojs.com/[DOMAIN-KEY]/image.min.js">

3. Get your images to work#

Your img tags are the ones responsible for displaying the images on your website. The following steps will show you how to:

Find your img tags
Adding the data-piio attribute
What the src attribute should contain

1. Find your img tags#

Open your code with an editor and search for <img . You will probably find something similar to this:

<img src="/images/myimage.png"/>

2. Adding the data-piio attribute#

Now that you found your img tags, you need to replace the src attribute with data-piio. Once you've accomplished that your img tags should look like this:

<img data-piio="/images/myimage.png"/>

3. What to put on the src attribute of your img tags#

The src attribute needs to be present on your img tags in order to have a valid HTML structure and should not be empty.

In order to have a valid HTML structure and a successful integration, we need to add a small image code to the src attribute. Here is the code we are going to add:

data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA

Success!#

A successful integration on your img tags will look like the following code:

<img data-piio="/images/myimage.png" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA" />

Other considerations#

You can place any absolute or relative URL in the data-piio attribute. Relatives URLs should start with / and keep them relative to your website root.
- Invalid relative url data-piio="image/image.png" ✖️
- Valid relative url data-piio="/image/image.png" ✔️
Use a NoScript tag to show images to users that have disabled scripts in their browser or have a browser that doesn't support scripts. Details here.

4. Using Piio Images with background images#

To use Piio Images on almost any HTML tag that is not an image, we can use data-piio-bck attribute. You can assign to this attribute the original URL of the image you want to show, and Piio Images will take care of the rest.

Example using a <div>:

  <div data-piio-bck="/images/background.png"></div>

The code above will set the background.png image as background on the div

Working with background images case by case#

There are many ways to show an image on a website, some html elements like the <body>, <div> or <a> allows you to use a property called background-image.

That property is usually set inline or in your css files. Inline example:

  <div style="background-image: url(images/background.png)"></div>

CSS example:

  <div class="with-background"></div>

  .with-background {
    background-color: #935d8c;
    width: 50px;
    height: 50px;
    background-image: url("images/background.png");
  }

Using `data-piio-bck` for inline style background-image#

First, you need to remove the code that is adding the background image.

  <div s̶t̶y̶l̶e̶=̶"̶b̶a̶c̶k̶g̶r̶o̶u̶n̶d̶-̶i̶m̶a̶g̶e̶:̶ ̶u̶r̶l̶(̶i̶m̶a̶g̶e̶s̶/̶b̶a̶c̶k̶g̶r̶o̶u̶n̶d̶.̶p̶n̶g̶)̶"̶></div>

Now you can add the data-piio-bck attribute to the element with the url of to the original image.

  <div data-piio-bck="/images/background.png"></div>

Using `data-piio-bck` for CSS background-image#

In this case, the URL of the image you want to use is defined on your CSS files. To properly load that image with Piio Images and optimize it, we will need to remove it from the CSS file and place it as data-piio-bck attribute in the HTML element.

  <div class="with-background"></div>

  .with-background {
    background-color: #935d8c;
    width: 50px;
    height: 50px;
    background-image: url("images/background.png");
  }

Once we apply those changes, our code will look like the following:

  <div data-piio-bck="images/background.png" class="with-background"></div>

 .with-background {
    background-color: #935d8c;
    width: 50px;
    height: 50px;
  }

Piio Image allows the div to inherit the CSS properties from the with-background class and applies the backgruond.png as background-image for the div

5. Art Direction#

Add a data-piio to each <source /> tag contained in the <picture> tag, and include the code for the transparent image in the srcset.

<picture>
  <source data-piio="/images/myimage-mobile.png" media="(max-width:799px)" srcset="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"/>
  <source data-piio="/images/myimage-desktop.png" media="(min-width:800px)" srcset="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"/>
  <img data-piio="/images/myimage-desktop.png"
    src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" />
</picture>

6. Video Posters#

Replace the poster attribute with data-piio.

<video controls data-piio="/images/video-poster.jpg">
  <source src="movie.mp4" type="video/mp4">
  <source src="movie.ogg" type="video/ogg">
</video>