# 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:

File: `components/sections/Hero.schema.ts`

```ts
    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:

File: `components/sections/PageHero.schema.ts`

```ts
    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:

**Astro**

File: `src/sections/pageHero.astro`

```astro
    {image && <Image image={image} media={{ tall: "(max-width: 767px)" }} class="page-hero__image" sizes="100vw" priority {...m.field("image")} />}
```

**Next.js**

File: `components/sections/PageHero.tsx`

```tsx
        {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:

**Astro**

File: `src/entry-pages/articles.astro`

```astro
    {a.image && <Image image={a.image} aspect="21:9" class="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
```

**Next.js**

File: `components/pages/Article.tsx`

```tsx
        {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](https://smoodly.io/docs/fields/media.md) 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:

File: `smoodly/config.ts`

```ts
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:

File: `components/sections/Gallery.schema.ts`

```ts
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`:

File: `components/Card.tsx`

```tsx
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](https://smoodly.io/docs/fields/richtext.md) covers the toolset.

Next, [Languages](https://smoodly.io/docs/languages/locales.md).
