Updated for Sparkle 2.2
There are a few ways to add an image in Sparkle:
Pixabay.com images are made available under a Creative Commons CC0 license. They can be used freely, even in commercial applications, without any attribution or credit, though some depicted content (people, places or brands) may require an additional authorization or release.
Sparkle will load most image types supported by the system, including JPEG, PNG, PNG (with transparency), GIF and TIFF. Additionally, Sparkle can load SVG vector images, which scale to different resolutions and devices.
SVG and GIF images are exported as is, while PNG and JPEG images are sized and compressed for the exact size used by the element. Other image formats are exported as JPEG, and then resampled to the required sizes.
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 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.
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).
When adding an image from your disk, Sparkle lets you specify the name of the image file in the output. The image description (sometimes referred to as the “alt tag”) isn’t normally visible but, if filled, it will be used by search engines and special browsers for people with disabilities.
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.
A series of checkboxes allow you to:
As with text, you can define what happens when an image is clicked on.
You can link to a specific point of the current document, to an external page, or to an email address but there are specific options in the menu to make an image zoom and be shown in a (dark or light) lightbox at a desired size and opacity.
Please report any shortcoming in this documentation and we’ll fix it as soon as possible!
Animate On Scroll
If checked, this control allows you to animate the way the image appears on the webpage. You can specify an effect, the direction and starting point of the movement and options like the duration and number of times the animation will repeat.
The final checkbox, Load When Visible, defers image loading until it is in view, to reduce page load and data traffic.