Image and colour fields
Image fields hold a picture and its alt text. Colour fields hold one of your site’s colours, which makes per-page themes possible without leaving the design system.
Image fields
An image field holds a picture and its alt text. It goes in an attribute, because its value is an address:
<img src="{{ cover:image:required }}" class="w:full h:auto bd:round-d3">
In the page text it would have nowhere to go, so <p>{{ cover:image }}</p> stops with “An image field goes in an attribute.” Any attribute works. A background image is style="background-image: url('{{ hero:image }}')", and a social card is <meta property="og:image" content="{{ share:image }}"> in the head, edited from Page settings.
In the editor
Click an image on the page to replace it, remove it or write its alt text, or drop an image file straight onto it. An empty image field shows a soft grey frame, so there is always something to click. Images are copied into the page's own folder and stored by file name:
"cover": { "file": "harbour.jpg", "alt": "Boats in the harbour at dawn" }
Because the file lives with the page, moving or renaming the page in the site view takes its images along. JPEG, PNG, GIF, WebP and AVIF are accepted.
What the built page gets
When the field is the src of an <img>, Verso finishes the tag for you:
- Alt text from the field, unless you wrote an
altyourself. Writealt=""for a purely decorative image. - Width and height, read from the file, so the page doesn't jump as it loads. Write your own
widthto opt out. - Smaller copies. A JPEG or PNG wider than 800 pixels gets copies 640, 1024 and 1600 pixels wide, and the tag gets a
srcsetwithsizes="(min-width: 64rem) 64rem, 100vw". Phones download less without you writing a line.
The copies are kept in .verso-cache/, keyed by the file's contents, so a rebuild only resizes what changed. GIF, WebP and AVIF are used as they are.
In a list, {{ item.cover }} gives the address of each page's image, and the build adds the same srcset. In <img src="{{ item.cover }}"> the image brings its alt text too, unless you write an alt yourself. Write alt="" when the title beside it already says the same thing.
Colour fields
A colour field lets an editor choose one of the site's colours. It renders that colour's CSS value, so it belongs in a style attribute:
<section style="background: {{ band:color }}">…</section>
In Page settings it appears as a row of swatches drawn from the colour tokens in your design. The page stores the token's name, not its value:
"band": { "color": "harbour-blue" }
So when you change harbour-blue in your design, every page that chose it follows. Saving a name that isn't one of the site's colours is refused.
Per-page themes
A colour field in a style attribute can only set raw CSS. Elevate's colour classes take tokens, not CSS variables. The way to let each page theme the whole design is a token whose value is a variable, with a fallback.
First, add the colours a page can choose, like harbour-blue and harbour-mist, in the Design panel. It keeps them in elevate/design/tokens.json.
Then add the tokens whose value is a variable. The Design panel only takes plain colours, so write these by hand in elevate/design/site.ts, the file for extras:
export const siteColors = {
// Set per page; the fallback is used everywhere else.
accent: 'var(--accent, #FF4F2B)',
'accent-soft': 'var(--accent-soft, #FFEEE8)',
};
Tokens in tokens.json win over site.ts. If the Design panel already has a colour with the same name, like the starter's accent, remove it there first, or give the variable token another name.
Last, set the variables from colour fields, high up in the template, and use the tokens as normal classes everywhere below:
<body style="--accent: {{ accent-colour:color:required }}; --accent-soft: {{ accent-tint:color:required }}">
<h1 class="font:h1:bold text:accent">{{ headline:text }}</h1>
<aside class="bg-color:accent-soft pd:d5">{{ note:rich }}</aside>
</body>
A page that picks harbour-blue and harbour-mist turns blue. Pages built from templates that don't set the variables use the fallbacks. The classes are ordinary Elevate classes, checked at build like any other, and the rich text class map can use accent too.
An empty colour field inside a style attribute writes --accent: initial, which tells CSS the variable has no value, so var(--accent, #1D1D1B) uses its fallback. Make the field required, as in {{ accent-colour:color:required }}, when every page must choose; required fields are marked in the editor and refused at build until a colour is chosen.