In order to display images from the SmartFrame Cloud on your web pages, you’ll need to install a SmartFrame Web Component in your web page code. The Web Component can be used and styled like any other HTML tag.


In order to install SmartFrame into your website, add the viewer code snippet in the section of your page code, just before the closing tag.

The script is unique for each account. You can find this in the Admin Panel under My Account > 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.


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.

<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>
  let sf = document.queryElement('smart-frame');
  sf.addEventListener('load', (e) => { console.log('SmartFrame loaded') });

SmartFrames can be styled using standard CSS:

  smart-frame.my-image { 
    max-width: 300px;
<smart-frame class="my-image" image-id="[image_id]"></smart-frame>

SmartFrames can also be dynamically added into the DOM:

  let sf = document.createElement('smart-frame');
  sf.setAttribute('image-id', '[image_id]');
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
string Unique 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. Visit Image > Image Details.

thumbnail-mode (optional) If this option is present, SmartFrame operates in a thumbnail mode. In this mode, all of SmartFrame’s UI, together with watermarks and tracking, are hidden and disabled. The maximum size of the image is limited to 800px.
theme (optional) string Identifier of the Theme to use. You can find it in the Advanced settings section 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.
placeholder (optional) string During the time when source image is being processed it displays a placeholder image provided in a form of image URL. Available only for customers using SmartFrame Image Source Connector integration.
enable-eis-loader (optional) During the time when source image is being processed it displays an animated loader with message “Your SmartFrame is being generated…”. Available only for customers using SmartFrame Image Source Connector integration.

Event reference

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’ }

  • right-click – right-click was detected
  • screenshot – when a screenshot attempt was made
  • programmatic – when an attempt to programmatically obtain access to the image was made
error This event is emitted in case of:

  • any problem with image itself and other sources (missing sfm, sfi, theme etc.)
  • malformed response (invalid data)
  • blocked embed
  • sandbox detection
  • deleted image

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 reserved on the page straight away, which minimizes shifting of content layers while images load onto the page.

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:

Full width
Custom width
Browser width

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


  • 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.