Schema field types

Every editable value in MagiCMS is a field on a schema. The field type decides which control the editor shows and which JSON type Astro receives.

You attach fields to a block, a collection, a global, a section or a page type. The types below are the same everywhere. Shared options (used on most types) are at the end of this page.

Start from what the person editing should do:

• One short line (title, label, button text) → text. Turn on inline-text markup only if they need coloured or broken lines inside that string.
• A paragraph or article with links, lists and emphasis → richtext.
• They must paste raw HTML (or SVG) that richtext would strip → html. Use sparingly.
• A link → url.
• A picture from the media library → image.
• A calendar day → date. A quantity → number. On/off → boolean.
• One value from a known set → select.
• A repeating group of sub-fields on the same record (FAQ items, cards) → list.
• A pointer to a separate collection entry (pick this person / this article) → collection. That type exists on block schemas. Collections themselves are a content type; see Content model.

A single line (or a multiline plain string if the schema allows it). Stored as a JSON string. Typical for titles, short labels and URLs you do not want validated as url.

Set formatInlineText: true when the string may contain MagiCMS inline markup ([[primary:word]], || line breaks). The Astro side then runs the inline-text helper. Details: Inline text.

A visual editor. MagiCMS stores HTML. In Astro, render it with set:html (usually inside a prose container). Use this for body copy. Do not use it for a one-line heading — that belongs in text.

A code editor for raw HTML. Authors can paste markup the richtext toolbar would not allow. Prefer richtext unless you have a concrete need (embed, custom SVG, <details>).

A validated address. Internal paths (/about) and full URLs (https://…) are both allowed. Open-in-new-tab and rel are not schema fields — the Astro block decides those.

Opens the media library and stores a path (typically /uploads/hero.webp on disk as src/assets/uploads/hero.webp). MagiCMS “folders” are labels in src/media.json; they do not create directories. Optional ratio (for example "16:9") opens a cropper and writes a sibling file such as hero_cropped_16x9.webp. Optional maxWidth / maxHeight write a scaled sibling. Optional showPOI (with ratio) lets the editor mark a point of interest so frontend object-cover keeps the right part of the picture. MagiCMS stores that as {field}Poi — pass it to CmsImage as poi, and draw the image in a cropping box (object-cover plus a set aspect or a wrapper with overflow-hidden). Details: Media.

In Astro, pass the path through CmsImage. Do not treat the stored string as a public CDN URL unless your project is set up that way.

A day stored as an ISO date string (YYYY-MM-DD). Format it in the template for humans; keep the ISO value for <time datetime> and sorting.

A JSON number. Optional min, max and step. Use for prices, counts and order indexes — not for phone numbers or IDs that must stay strings.

A toggle. Stored as true or false. Good for “show this”, “invert colours”, “this category is required”.

One value from a list. Three ways to fill the list:

1. Fixed in the schema: "options": ["left", "center", "right"].
2. From another list field on the same schema: "optionsFrom": "categories".
3. From a list on a global: optionsFromGlobal (icon catalogs are the usual example).

The stored value is the option string, not a label. Keep option ids stable.

An array of objects. MagiCMS adds an _id per row. You define sub-fields (text, image, and so on) for each row.

Translation has two mutually exclusive patterns:

1. The whole list differs per language — set translatable: true on the list. Each language file holds a full array (different number of items is allowed).
2. Same rows, translated copy — leave the list not translatable; mark sub-fields translatable. Structure stays in the base file; each language file overlays copy by row _id.

Do not turn on both. More detail: Multi-language.

On a block, this field stores the slug of an entry in a named collection (and optionally pagination hints such as perPage). The block’s Astro file loads that collection at build time and renders the entries.

It does not create a collection. You still add the collection under src/content/<name>/ (or in MagiCMS → Collections) first.

• label — what the editor shows.
• translatable — if true, MagiCMS stores the value per language file instead of on the shared structure.
• required — MagiCMS blocks save when empty.
• helpText / placeholder — guidance in the form.
• default — initial value for new blocks or entries.

Image-only extras: ratio, showPOI, maxWidth, maxHeight. Select-only: options, optionsFrom, optionsFromGlobal.