Intelligently responsify your site's images in seconds. To use salieo.js you'll need to set up your site on www.salieo.com first.
salieo.js is a lightweight browser library that automatically positions and scales your images so they display properly on all devices with any aspect ratio or pixel density while retaining the most important parts of your images in view. salieo.js uses cropcalc-js to calculate the best crop for an image based on data returned from the Salieo API.
salieo.js requests crop direction information from the Salieo API for all enabled images on your site. If the Salieo API has not processed this image before it may take a second to do so (resulting in a small delay between the time your images load and when they are repositioned and/or scaled by salieo.js). Don't worry though, this only happens once.
After the images are processed the first time by the Salieo API, the results are cached on a global CDN to enable near instantaneous delivery of the data for future page loads anywhere in the world. This way, subsequent page loads should not see any visible jump when salieo.js repositions the images. The data is loaded and the transformations are applied all before the image loads.
salieo.js can work on any element with a CSS background-image or any <img> element. Just add the salieo class (or the custom class you specified with the img_class option) and you're off to the races.
All modern browsers (and IE11) are supported by salieo.js:
NOTE: IE11 and Edge currently have an issue with allowing script access to window.localStorage when a page is accessed locally with file:// As a result, salieo.js will not function on IE11 and Edge on pages loaded in this fashion. salieo.js works just fine on IE11 and Edge when pages are loaded over http:// and works fine with pages loaded through file:// on all other browsers.
Get started quickly by including salieo.js in your site's <head> with the following:
<script src="https://cdn.jsdelivr.net/npm/salieo.js@0/dist/salieo.min.js" defer></script>Or if you'd rather use your own build system that's fine too. As salieo.js is built as a UMD bundle, you can use it with just about any module loader you like.
npm install salieo.jsCreate an instance, passing in your options.
var instance;
document.addEventListener("DOMContentLoaded", function() {
instance = new salieo({
site_id: "YOURSITEID"
});
});NOTE: If an salieo instance isn't initialized early enough during page load, your images may not be positioned properly before they are displayed resulting in a noticeable jump when they reposition. To avoid this, ensure the following:
- As mentioned in setup, if you are using a
<script>tag to load salieo.js you should include it in your<head>not at the end of<body>as one may be used to. As long as the script is loaded with thedefertag it won't block rendering while loading and will ensure salieo.js is fully loaded before theDOMContentLoadedevent fires. - A salieo instance should be created when the the
DOMContentLoadedevent fires. Creating the instance before the DOM has fully loaded could result in salieo not finding all images that need processing. Conversely, creating the instance after theDOMContentLoadedevent, (i.e. on theloadevent) will likely not give salieo enough time to reposition the images before they are displayed.
Repopulates the list of images and avoid areas and reprocesses all images, fetching data from the Salieo API if necessary for new images.
Required options have a *
The ID of your site used for identification with the Salieo API. This can be found from your Salieo Dashboard.
var options = {
site_id: "ABCDEF"
};Default: "salieo"
The class of <img> or objects with a background-image to that should be processed.
Default: "salieo-avoid"
The class of objects that should be avoided when positioning a subject. More information is in the Avoid Areas section.
Default: true
If enabled, salieo.js will call refresh() when changes to the size of any avoid area or image is detected using ResizeObserver.
As a side note, due to the poor browser support for ResizeObserver, salieo.js bundles a polyfill.
Default: undefined
Can be set to an object of cropcalc-js options that will apply to all images. These options can be overridden on a per-image basis by setting Crop Options on an image.
*NOTE: The target_width, target_height, actual_width and actual_height options cannot be specified here as they are set on a per-image basis.
var options = {
crop_options: {
zoom: "auto"
}
...
};Default: false
If enabled with true, salieo will not suppress any error messages resulting from failed API calls, helping pinpoint any issues.
Options that modify how an image is cropped can be specified on a per-image basis through the use of data-salieo-OPTION attributes. These options are passed directly to the cropcalc-js algorithm. A full list of available options can be found here.
NOTE: The target_width, target_height, actual_width and actual_height options cannot be specified as they will always be overridden by the salieo with the appropriate values for a given image.
NOTE 2: salieo.js automatically takes DPR into account by dividing the actual_width and actual_height of an image by the DPR before passing them to cropcalc-js. Thus, salieo.js will never provide a crop that forces the image to be scaled up past a 1:1 ratio with the physical pixels on the screen unless an image with insufficient resolution to fill the desired area has been provided. salieo.js will always force images to at least cover the available area.
Example:
This example sets the cropcalc-js option zoom to "auto" for this image.
<img src="https://www.example.com/example.jpg" data-salieo-zoom="auto">Below are the mappings from the cropcalc-js options to the associated data-salieo-OPTION:
zoom -> data-salieo-zoom
focus.x1 -> data-salieo-focus-x1
focus.x2 -> data-salieo-focus-x2
focus.y1 -> data-salieo-focus-y1
focus.y2 -> data-salieo-focus-y2
NOTE: Unlike the cropcalc-js options, the focus sides should not be specified in pixels. Instead they should be specified in percentage values (just the number, without the % sign). This way when the viewport resizes, the desired focus area can still be achieved with the new size of the image.
Example:
This example sets the focus area for this image to be the left half of the crop.
<img src="https://www.example.com/example.jpg" class="salieo" data-salieo-focus-x2="50">Avoid areas provide an easy way to ensure the subject of an image is positioned in free space, not behind text or another overlay. See a JSFiddle example.
The salieo-avoid class (or a custom class as specified with avoid_class) can be applied to any object that is positioned over an image that salieo will process. Salieo will then automatically set the focus for that image to be the largest rectangle of free space either to the right, left, top or bottom of that object. The zoom option for that image will also be set to "focus".
NOTE: Crop Options specified on an image always take precedence and will override any settings set by the avoid area calculation. For example, you could set data-salieo-zoom to false on an image while still using an avoid area to simply shift the image into the appropriate position without any zooming. Global crop_options set in the options passed when initializing salieo.js will, however, be overridden by the options set through the avoid area calculation.
The behaviour of an avoid area can optionally be controlled by applying the data-salieo-avoid attribute to the element with the avoid_class.
NOTE: The data-salieo-avoid attribute should be applied to the element to be avoided, not the image.
Example:
This example sets any images that fall below this text element to center the subject in the free space to the right of the text element.
<p class="salieo-avoid" data-salieo-avoid="right">Avoid this!</p>This is the default setting. The area of free space to the left, right, top and bottom of the element to be avoided will be calculated. The free space region with the largest area will be selected and the subject of the image being positioned will be centered within it.
If the area of the largest region is not at least 20% larger than its opposite region (i.e. the left region is opposite the right region, and the top opposite the bottom, etc.) the avoid area will be ignored and the focus area will be the entire width and height of the image element. For example, this is especially helpful for responsive designs where an element to be avoided may be positioned near the left for larger screen sizes (resulting in the right region being selected for the focus area) but center positioned for smaller screen sizes resulting in the avoid area being ignored and the subject being centered behind the text.
For more control, the behaviour of the avoid area region selection can be selected manually with one of the options below.
The region to the left of the element to be avoided will always be selected as the focus area.
The region to the right of the element to be avoided will always be selected as the focus area.
The region above the element to be avoided will always be selected as the focus area.
The region below the element to be avoided will always be selected as the focus area.
MIT. © 2018 Salieo
