Updated for Sparkle 2.6
Please report any shortcoming in this documentation and we’ll fix it as soon as possible!
Images are the best way to make your page interesting and distinctive, and they obviously inform, provide context and set the mood. Images are also the main source of page weight, because browsers download them immediately along with the page.
For these reasons there are several ways to integrate images in the page and many options.
You add an image by dropping it into the canvas straight from the Finder or by adding it from the “More” popup. You can replace an existing image by dropping it over the image thumbnail in the settings, or over the image in the canvas.
An alternative to using the image element is setting the image as the background of a box.
Images have a basic placeholder look, which can be useful when you first rough out a layout without also adding content.
The basic and most common image type is a bitmap image, which includes images coming from digital photography or image creation tools that aren’t expressly vector-based.
Sparkle will load most bitmap image types supported by the system, including JPEG, PNG, PNG with transparency, GIF, TIFF and digital negative (raw) camera files.
GIF images will be exported as is, while PNG and JPEG images are resized and compressed for the exact size used by the element. Other image formats are exported as JPEG, and then resized to the required sizes.
Image options include a title text, which will be shown as a tooltip in most browsers, and a description text (sometimes referred to as the “alt tag”), which is an accessibility option used by screen readers and other assistive devices, but not otherwise visible in the browser.
The image frame in the canvas is the maximum space for the image. How the image fits the frame is controlled by the alignment and stretching controls.
If the “Stretch” checkbox is disabled the image will maintain its original dimensions (and will be cropped or letterboxed if necessary). Its position in the element frame can be aligned horizontally and vertically by using the six buttons: left, middle, right, top, middle, bottom.
If the “Stretch” checkbox is enabled, an appropriate scaling factor will be applied by Sparkle. The “Fit” button ensures the entire image is visible, but will produce a horizontal or vertical letterboxing. “Fill” ensures the image covers the entire frame, but the image will be clipped at the frame edges.
The “resolution report” bar below the stretching controls helps you assess the quality of the output image and whether there are enough pixels for high dpi (retina) and even normal size usage. As you resize the image the bar updates automatically. Ultimately you should ensure you don’t drop below 2x: many devices will show an image that’s perceivably low resolution.
Sparkle supports browsers running on high dpi (retina) devices or very high dpi (3x retina). When the source image size is sufficient, the image will be automatically generated for normal (1x), high dpi (2x) resolutions, or very high (3x). Image generation options are available site-wide in the settings panel.
Tip: drag-and-dropping an image with a name ending in @2x (for example email@example.com), its dimensions will be halved and it will be placed on the canvas at the 1x size. Likewise for a @3x suffix.
Sparkle can load SVG vector images, which scale to different resolutions and devices. Like for bitmap images you can drop them right on the canvas, or onto existing images. SVG images will be exported as is, no resolution report is necessary because they inherently scale in a crisp way to multiple devices.
Vector images are generally very compact and their mobile-friendly nature makes them ideal for whenever you don’t need photography.
SVGs are easily found on the web and can be produced by many desktop apps, we definitely encourage their use.
Sparkle supports the hybrid photo-video combinations that modern iPhones can shoot. By entering both the image and the movie file exported from Photos, you can produce a page that lets your site visitors see and interact with the Live Photo.
You can get the still and movie files for a Live Photo by syncing your photos to Photos on the Mac and then picking the photo and using the File -> Export Unmodified Original command.
Sparkle makes it super convenient to pick a stock image from the free pixabay.com collection of over 1.3 million images. All images are made available under a Creative Commons CC0 license.
They can be used freely, even for commercial use, without asking permission from the image author. However it is still your responsibility to make sure the depicted content (persons, logos, private property, etc.) is suitable for your website and does not infringe any rights.
Images from network location
This is mainly used to hotlink images in other web locations, it’s a relatively infrequent case and Sparkle can only have very limited control, so the options are very minimal.
Your website will effectively be using someone else’s bandwidth, so you should ensure the owner agrees with your hotlinking.
You do not need to resize or compress images before adding them in Sparkle. When you publish or export the website, Sparkle will resize and recompress the images as needed. In fact it’s probably best if you are generous with the image dimensions and quality.
The generous dimension gives you the composition freedom to move and size the image anywhere in your layout without being constrained by a pre-cut size, keeping an eye on the resolution report tells you if the quality of the published image will be degraded. By using highest quality images you will help Sparkle minimize compression artifacts when publishing, ensuring the best results.
This suggests that it’s probably best if you don’t prepare images in an external application before importing them to Sparkle.
In general, if you add multiple devices Sparkle will generate multiple images and serve only the one with optimal resolution and density for each viewing device. This allows modern browsers to only download what they need, resulting in improved performance and savings in data transfer.
Ultimately for each input image Sparkle will be generating an image for each device and each screen density, both in JPEG and in WebP (if the option is set in the settings).
Further down in the inspector, common to all image types, you can specify an image border. The border is added outside of the image extent. You can either have a single border setting for all sides or a separate setting for each edge, the canvas will show the exact output.
Image corner rounding
Image corners can be rounded with a specified pixel radius, you can opt for each corner to be rounded or not.
In an extreme rounding setup you can have a square image with the radius exceeding the image size, ending up with a circular image. Incidentally this is a popular style for a profile picture look.
The border, when visible, will follow the rounded edges.
Image drop shadow
Drop shadows used to be cool and trendy, for this reason alone their use can make your design look dated.
However used carefully and tastefully they can add a subtle 3D effect and provide an organic sense of depth.
Adjusting the opacity can be useful for some visual effects. Opacity affects the image content as well as the border and the shadow, if present.
Image filters are a quick way to enhance or alter an image. Adding filters is non-destructive, meaning the original image is preserved. The filters can be combined, including used multiple times and in different orders.
As with text, you can define what happens when an image is clicked on. The usual On Click actions apply, plus an image-specific option to zoom the image in the window, shown in a lightbox that overlays the page.
Scroll animation is common to several elements, see the animations page.
Load when visible
Browsers have smarts to begin downloading images even before having loaded the entire page. If your page contains many images, they will all be queued up for download, and this can effectively make the overall page load be slower. The “Load when visible” option delays image load, so it is worse for images visible at load time, but by setting it for images not initially visible it will speed up overall page load time. Additionally if the site visitor never scrolls down to reveal all images, fewer images will have been downloaded so it will save on bandwidth as well.