Overview
You will need to install a SmartFrame Web Component in your webpage code in order to display images from the SmartFrame Cloud on your webpages.
The SmartFrame Web Component <smart-frame> can be used and styled like any other HTML tag.
Installation
In order to install SmartFrame Web Component into your website, add the viewer code snippet into the <head> section of your website.
The script is unique for each account. You can find this in the Admin Panel under Account settings > Integration.
The script will appear like this:
<script type="text/javascript" src="https://static.smartframe.io/sf/9c9ffb7a0ed0cd60846bffcf2bbb7458/smartframe.js"></script>
This script registers the new custom <smart-frame> Web Component. At this point, <smart-frame> is ready to be used on the web page.
| The SmartFrame Web Component is compatible with all evergreen browsers. If any of the browser features are missing, an appropriate polyfill will be automatically loaded. For further details, please refer to the browser compatibility page. |
Usage
Insert the <smart-frame> tag wherever you would like your images to appear. The value [image_id] needs to be replaced with your image ID (case-sensitive).
<smart-frame image-id="[image_id]"></smart-frame>
The appearance of SmartFrames can be controlled through the use of a number of attributes, for example:
<smart-frame image-id="[image_id]" theme="myzoom" disable-hidpi></smart-frame>
SmartFrame emits standard Javascript DOM events:
<smart-frame image-id="[image_id]"></smart-frame>
<script>
let sf = document.queryElement('smart-frame');
sf.addEventListener('load', (e) => { console.log('SmartFrame loaded') });
</script>
SmartFrames can be styled using standard CSS:
<style>
smart-frame.my-image {
max-width: 300px;
}
</style>
<smart-frame class="my-image" image-id="[image_id]"></smart-frame>
SmartFrames can also be dynamically added into the DOM:
<script>
let sf = document.createElement('smart-frame');
sf.setAttribute('image-id', '[image_id]');
document.body.appendChild(sf);
</script>
| Unlike the img tag, smart-frame requires a closing tag |
Attribute reference
You can control the appearance and behavior of your SmartFrames by inserting attributes into the shortcode, using the following syntax:
<smart-frame image-id="[image_id]" [attribute1] [attribute2]="[optionalvalue]"></smart-frame>
| Key | Value | Description |
|---|---|---|
| image-id (required) |
string | Unique case-sensitive ID of the image.
If you added the image using SmartFrame API, it’s the same ID as provided in the API request. If you use the Image Source Connector, it’s the ID we agreed to use. If you uploaded the image using the SmartFrame Admin Panel, you can find the ID in the Admin Panel. Click on the image in the Images panel before selecting Image Details. |
| thumbnail-mode (optional) |
If this option is present, SmartFrame operates in a thumbnail mode. In this mode:
|
|
| theme (optional) | string | Identifier of the Theme to use. You can find it on the Overview page within each Theme in the Admin Panel. |
| disable-hidpi (optional) | When used, SmartFrame will ignore the physical resolution of the display used to view the SmartFrame when choosing the image size file to download, and will instead rely only on logical resolution. | |
| wait (optional) | When the ‘wait’ attribute is present in the code, rendering of the SmartFrame will not be initiated. Use this if you want to load your page with SmartFrame disabled. When the attribute is removed, SmartFrame will be displayed. |
SmartFrame emits custom Javascript events that can be listened to using a standard addEventListener method.
| Event name | Description |
|---|---|
| preload | Low-resolution placeholder finished loading, SmartFrame present in DOM |
| load | Image file finished loading |
| resize | Viewport size has changed |
| danger | An image-theft attempt has been detected. A detail object is provided, with the type of image theft attempt detected:
{ ‘origin’: ‘type’ }
|
| error | This event is emitted when there is:
|
Test mode
This is activated when ‘__sfDisableTracking’ global window variable is set to true.
The snippet that sets it (below) needs to be added in <head> section of the page
<script>window.__sfDisableTracking = true;</script>
How SmartFrame renders on the page
As soon as SmartFrame is initiated, a very low-resolution JPEG placeholder is displayed at the same size as the target image. This reduces the perceived loading time and creates a smooth user experience. In addition, the image height is immediately reserved on the page, which minimizes shifting of content layers while images load.
If the SmartFrame lies outside the viewport, it will be prepared for display. Further loading is paused to save bandwidth until the SmartFrame comes into view (lazy loading). The SmartFrame is initiated and the content is displayed as soon as the user expects to see it. At that point, the image is rendered on a <canvas> object placed inside the <smart-frame> tag, which eliminates the need for an image file and prevents unwanted image downloads.
SmartFrame detects the screen size and pixel density of the user’s display, and requests the most appropriate resolution from the server. This optimizes bandwidth and ensures that the image is always clear, even on more demanding HiDPI or Apple Retina displays. When the image size is changed – due to resizing the browser window, resizing the container layer, or changing the screen’s orientation – the image on the page is resized to fit the new size. If SmartFrame determines that it may not look sharp, a higher-resolution image is requested from the server and automatically inserted into the frame. This method is also activated when a user pinches a mobile or tablet screen to zoom into the image.
You can adjust the SmartFrame size on the demo below and observe the loading behavior:
Styling SmartFrame with CSS
<smart-frame> replicates <img> tag behavior as closely as possible. It’s a Web Component and can be styled with plain CSS. SmartFrame is an inline-block element by default and maintains aspect ratio.
If you are converting your existing website to use SmartFrame, your CSS styles might be mapped to <img> selector. In this case, you will need to map those styles to the <smart-frame> selector.
Differences between <img> and <smart-frame> styling
SmartFrame emits custom Javascript events that can be listened to using a standard addEventListener method.
| Image file | SmartFrame | |
|---|---|---|
| When the aspect ratio is changed | stretch | crop |
| When the image container is enlarged | upscale the existing image | load a higher-resolution image to match the new size |
| When the image is outside the viewport | always displayed | only displayed if in the viewport |
| To limit the maximum height of the image | use max-height CSS property | use sf-max-height CSS property |
| To limit the maximum width of the image | use max-width CSS property | use sf-max-width CSS property |
Notes:
- Scaled SmartFrames will retain the original aspect ratio unless width and height properties are set to a fixed value, just like an <img>
tag.
- By default, SmartFrame will not exceed the parent container width.
You can use the demo below to test a SmartFrame’s behavior when resizing.