Images and crops
An image field stores which asset to show and how to frame it. Smoodly's media host cuts the framed area at the width the layout needs, in a modern format, and the image component renders it without layout shift.
Aspect ratios
An image field declares the ratio of the box it renders into, or several:
image: f.image({ aspect: "4:5" }),The crop tool locks to the declared ratio, and with several, ["3:2", "1:1"], a switch lets the editor pick one per use. Without an aspect the crop is free and the box takes the crop's own ratio. Declare one where the layout fixes the shape, such as a card or a hero, so the box is known before the image loads. A crop counts only at the ratio the code declares now: change a field's ratio, or a named crop's, and the crops saved at the old one give way to the focus point at the new ratio until an editor frames them again.
Named crops
Where the layout needs a different shape per screen, name a crop for each instead of one aspect:
image: f.image({ crops: { wide: "21:9", tall: "4:5" } }).optional(),The editor gets a tab per crop in the crop tool, all sharing one focus point. A crop nobody framed follows the focus point at its ratio, so most images need no second look; a framed one keeps its rectangle. The first crop is the main one: the resolved value's crop and aspect are its, and crops holds every one by name.
The view says where each crop applies, with a media query per name. Breakpoints live here, in code, never in content:
{image && <Image image={image} media={{ tall: "(max-width: 767px)" }} class="page-hero__image" sizes="100vw" priority {...m.field("image")} />} {image && <SmoodlyImage image={image} media={{ tall: "(max-width: 767px)" }} className="page-hero__image" sizes="100vw" priority {...m.field("image")} />}The component renders a <picture> with one <source> per named crop in media, in the order given, and the main crop as the <img>; each has its own widths and its own width and height, so nothing shifts on either screen.
The crop tool
Edit on a filled image field opens the tool: the full image with a draggable crop rectangle, a draggable focus point, an alt text box for this use and a live preview at the chosen ratio.
- The crop picks the part of the image to show.
- The focus point decides what a crop nobody framed shows, and what stays visible when a view places the image in a box of another shape.
- The alt for this use overrides the asset's own alt from the library when set.
The value the field stores is the asset's id plus this framing. The same photo can be cropped differently in a card and in a hero, and a change in one place leaves the other alone.
Rendering
The image component renders a box at the crop's ratio and a plain <img>, with the dimensions set so nothing shifts as it loads:
{a.image && <Image image={a.image} aspect="21:9" class="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />} {a.image && <SmoodlyImage image={a.image} aspect="21:9" className="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}Here an article's photo, cropped at 3:2 for its card, renders at 21:9 on the article page: the aspect prop overrides the ratio for this placement and the focus point keeps the subject in view. Image, video and file lists the other props.
The bytes come from Smoodly's media host, media.smoodly.io. It cuts each image to the area its stored value gives (the editor's crop, or the ratio around the focus point, or the whole image) and serves the cut at one width from a fixed list (320, 640, 750, 828, 1080, 1280, 1536, 1920, 2560 and the cut's own width; from 640 to 1080 the steps next/image uses), at quality 75 unless you choose another, in AVIF where the browser takes it and WebP otherwise. The srcset lists those widths and sizes tells the browser which one the layout needs, so a visitor downloads only the cropped area at about the width it is shown. The page opens a connection to the media host while its HTML is parsed. There is no image config in your project and no image optimizer on your host: neither next/image nor Astro's /_image is involved. An SVG is served as uploaded.
A static Astro build writes every image its pages show into its own output, under /_smoodly/media/: each listed width in AVIF and WebP, offered by type in a <picture>, since a static host cannot choose a format per browser. The pages then need nothing from Smoodly at run time and their images come from your own host; a publish reaches them with the next build. Videos and files keep their media address. In local development the service serves the originals and the component crops them in CSS.
Quality and width
Every image is served at quality 75 with a srcset up to the cut's own width unless you say otherwise, in three places; the nearest wins. The whole site, in its config:
import { defineConfig } from "smoodly";
export const config = defineConfig({
registry: {},
locales: { default: "en", supported: ["en"] },
media: { quality: 85, maxWidth: 1920 },
});A kind of image, on its field:
import { f } from "smoodly";
export const photos = f.list(f.image({ quality: 95 }));One placement, with the same two props on Astro's Image and Next's SmoodlyImage:
import { SmoodlyImage, type ResolvedImage } from "smoodly/image";
export function CardImage({ image }: { image: ResolvedImage }) {
return <SmoodlyImage image={image} quality={60} maxWidth={828} sizes="(min-width: 900px) 25vw, 50vw" />;
}quality is one of 50, 60, 75, 85, 95 or 100; any other number is refused when the config loads or the page renders, since each quality is a separate image the media host makes and keeps. 50 and 60 suit thumbnails and grids, 75 matches what next/image serves, 85 and above suit photography. 100 is heavy: a wide image at 100 weighs several times the same one at 85 for a difference few eyes see.
maxWidth caps the srcset at the listed widths under it and adds no width: maxWidth: 1000 lists 320, 640, 750 and 828. Use it where the layout never shows an image wide, so a sharp screen does not fetch more than the layout needs. Editors see neither setting. In local development the originals are served, so both apply only on the media host.
Images inside richtext
A body image, inserted from a toolset with image in its nodes, stores the asset, an alt and a caption, and no crop: it renders at its natural ratio through RichText, with the text column's sizes and the project's media.quality and media.maxWidth. Richtext and elements covers the toolset.
Next, Languages.