Images can be added in a number of ways: by dragging directly from the desktop into a page; by dragging onto the images icon in the top menu bar; by opening the images menu and dragging into it; or by selecting image files by clicking Upload.
Accepted formats are JPEG, PNG, GIF, SVG. File size limit is 25MB per image. Videos can also be added in the same way — accepted formats are MP4, MOV, and WebM. The size limit is 25MB per video. (Read more about adding videos here.)
Tip: to replace an image in the page while keeping its local properties like link, sizing, border, rotation, etc., open the images menu and drag & hold the new image onto the image you want to replace.
Sizing
The Image Settings menu in Site Settings contains options to change the way images are displayed by default, and this can be overriden locally for individual images. Images are, in most cases, not allowed to grow beyond the width of their container. This container is always a column, gallery, or page.
Galleries have their own layout designs which dictate a specific height or width for a given image. These designs can be specified through a gallery's settings and often on an image-by-image basis. For example, a Grid gallery might have a three-column layout, and the images inside can be set to occupy one, two, or three columns.
Pages and Columns only limit the width of the images they contain, which can otherwise grow as tall as needed in proportion to their width. From there, the image settings can be used to refine the maximum size of each image, or change how their size is limited. The settings are as follows:
Scale by Width
A setting of 100 means that an image will scale to fit 100% of the width of its container at a maximum. A setting of 50 means that the image will scale to 50% of the width of its container, and so on. Different CSS units can be used: A setting of 400px will limit the image to 400px wide or the width of its container, whichever is smaller.
This is useful when you want an image to be sized purely in relation to the width of its container, like a full-bleed header image that needs to reach both the left and right edges of the website. This sizing behavior is also relatively predictable, regardless of the dimensions of the browser window.
Scale by Height
A setting of 1 means that the image will be one base unit tall (one "rem" ). These units are the same used by Cargo elsewhere in the setting of font sizes, padding, borders, gutters and margins. Regardless of the specified height, it will not expand beyond the width of its container.
This is useful for smaller images that need to keep a consistent relationship to surrounding text or design elements, like small icons, logos or inline graphics. Different CSS units can be used: A setting of 50% will limit the height of the image to 50% of the width of its container, and a setting of 80vh will limit the height of the image to 80% of the browser's viewport height.
Scale to Fit
For every page, a value that represents the maximum available uncropped height is calculated. This value is the height of the browser viewport minus the accumulated dimensions of all the surrounding margins, padding, borders and pinned pages. For example, if a page has 10px of padding on all sides and the browser window is 800px tall, that value would be equal to 780px. This value is fixed to a percentage: A setting of 100 means that the maximum height is 100% (780px) of that value, 50 is 50% (390px) and so on.
This is useful when you want an image to fit entirely in the browser viewport, regardless of its aspect ratio or the width of the image's container.
Captions
Captions can be added to images and videos via the image settings menu: right-click an image or video and click on Caption..., which will insert “Lorem ipsum...” as a placeholder. Captions are styled according to the Caption text style, which can be edited in the Text Styles menu (the “Aa” icon in the right menu bar). It’s possible to apply different text styles to the caption, and captions can contain text formatting like bold and italic, as well links.
To change the positioning of the caption relative to the image or video, open the CSS Editor (the “</>” icon at the bottom of Site Settings) and search for .caption. To change how captions are displayed in Quick View, find .quick-view .caption.
Zoom
When Image Zoom is enabled (open Site Settings, then Image Settings), clicking an image or video enters Zoom mode, which maximizes it to fit to the window size. The size and positioning is configured in Quick View Settings (in Default Page Settings). Read about Quick View here. It’s possible to locally exempt images and videos from Image Zoom in the Image Settings menu (right-click an image and Disable Zoom). When an image or video is linked, Image Zoom is inactive. To change the style of the navigation buttons when zoomed-in, open the CSS Editor and search for ::part(slideshow-nav).
Scroll Transition
When Scroll Transition is enabled (open Site Settings, then Image Settings), images fade-in and animate upwards as they come into view while the page is scrolled. This effect also applies to Videos, Image Galleries, and Thumbnail Indexes. When this option is enabled, it can be turned off locally for individual images or videos, in the Image Options menu.
Effects
A number of “Effects” can be applied to images globally — like Border and Drop Shadow — in the Site Settings menu. Additional Effects can be applied locally: right-click an image and click the Effects link in the image settings menu to add effects like Rotation, Blink, Eyeroll, and Draggable. Read about Effects here.
Custom Styling
To apply a custom style to a specific image, right-click it and look for “HTML”. Here you can add a class attribute and target that from the CSS (the “</>” icon at the bottom of Site Settings). For example, if you’ve added a Border to all images in Default Page Settings but want to remove it from one image only, add a “no border” class in the CSS Editor:
media-item::part(media).no-border {
border: none;
}
And then add the class to the image:
<media-item class="no-border" hash="I1370492670470899008647490175015"></media-item>