Working with Fields

Add content fields to blocks and pages to make them editable.

Add fields to let editors change specific values in your block, such as a headline, image, or link. You choose the field names and use them in your Svelte code.

Watch the workflow

Build a component with an editable field

Watch the workflow in Primo.

Download video · Download captions

Read the walkthrough

1. Open the page type to create a reusable block.
2. Switch to content and create a Text field.
3. Label the field Headline. Its key is headline.
4. Set the default content for the field.
5. Reference the field in your component markup.
6. Preview the result, then create the block.

Where fields live

Fields define editable content on sites, page types, and blocks. A definition specifies the label, key, and type; the content holds its value. Use site fields for global content, page fields for content that describes a page, and block fields for an individual section.

Add fields in the browser

You need developer access to change field definitions.

1. Open the block

   Create or open a block in the library or the page type’s Blocks tab. Switch to Content to add fields and default content.

2. Set the label, key, and type

   Add a field with a clear label, such as Headline. Set its key to headline and its type to Text. Keys are case-sensitive and must match the variables in your block code.

3. Write the markup

   Reference the field directly. The browser compiler supplies field variables automatically. You can omit $props() in this workflow; if you declare it yourself, include every field the block uses. Use Svelte 5 runes instead of export let.

   component.svelte

   <section class="hero">
     {#if headline}
       <h1 data-key="headline">{headline}</h1>
     {/if}
     {#if image?.url}
       <img src={image.url} alt={image.alt || ""} data-key="image" />
     {/if}
   </section>
   

   Add image as an Image field before using this example. data-key connects the element to its field for inline editing; it is especially useful when content repeats.

4. Set default content and save

   Enter a headline and, optionally, select an image. Save the block. Defaults seed new sections; later edits to a section belong to that section.

5. Verify on a page

   Add the block to the page type’s available blocks, place it on a page, and edit both inline and through Edit content. Save the dialog and confirm the page shows the values you entered.

Define fields in files

A block needs config.yaml, component.svelte, fields.yaml, and content.yaml. Create them under sites/my-site/blocks/hero/:

config.yaml

name: Hero

fields.yaml

- name: headline
  label: Headline
  type: text
- name: image
  label: Hero image
  type: image
  config:
    maxSizeMB: 2
    maxWidthOrHeight: 1920

content.yaml

headline: A place to grow
image:
  url: ""
  alt: ""

For component.svelte, you can declare the field props explicitly. This works in the browser, in CLI 0.2.1, and with older static builders:

component.svelte

<script>
  let { headline, image } = $props();
</script>

<section class="hero">
  {#if headline}
    <h1 data-key="headline">{headline}</h1>
  {/if}
  {#if image?.url}
    <img src={image.url} alt={image.alt || ""} data-key="image" />
  {/if}
</section>

fields.yaml is a bare list; content.yaml is an object keyed by field name. Use config for field-specific options. Keep existing _id values when editing an export and omit them for new fields.

Run primo validate -d sites/my-site from the workspace root. If primo dev --author files is already running, wait for it to import the files and check the preview.

Choose supported field types

See Field types for the complete list. Use:

• Text for plain text, including email addresses and phone numbers.
• Rich Text or Markdown for formatted content; render the resolved HTML with {@html content}.
• Image for images; check image?.url before rendering.
• Link for a URL and label; check link?.url and use link.url and link.label.
• Toggle for true/false values (type: switch in files).
• Repeater for a list of objects and Group for one object.
• Info for instructions displayed in the editor.

There are no built-in Email, Textarea, Tags, Video, or general File field types. Use Text for emails, a Repeater of Text fields for tags, and URL for externally hosted videos.

Repeaters and groups

Nested definitions use subfields, not fields:

fields.yaml

- name: cards
  label: Cards
  type: repeater
  subfields:
    - name: title
      label: Title
      type: text
    - name: link
      label: Link
      type: link

content.yaml

cards:
  - title: Visit our studio
    link:
      url: /about
      label: About us

component.svelte

<div class="cards">
  {#each cards ?? [] as card}
    <article>
      <h2 data-key="title">{card.title}</h2>
      {#if card.link?.url}
        <a href={card.link.url} data-key="link">{card.link.label}</a>
      {/if}
    </article>
  {/each}
</div>

For a Group, use the same subfields structure with type: group. Its value is one object rather than an array. Guard optional nested values before accessing them.

Reference site and page fields

A field named logo in a block does not automatically read the site’s logo. Add a Site Field reference and select the source field. Use Page Field to reference a field on the current page.

• Site Field references are available in page types and blocks.
• Page Field references are available in blocks.
• Editing a reference through the content form updates its source value. A site-field change can affect many pages; a page-field change affects that page and listings that reference it.
• Reference fields do not support inline editing. Use the content form or edit the source field.

fields.yaml

- name: logo
  label: Site logo
  type: site-field
  config:
    field: logo
- name: title
  label: Page title
  type: page-field
  config:
    field: blog-post--title

Create the site Image field logo and a Text field title on a blog-post page type before adding these references. In file-authored blocks, a Page Field target uses <page-type-folder>--<field-key>. In the browser, select the page type and source field.

Watch: Connect site and page field references

This custom example shows the source of each reference and which pages an edit affects.

Download video · Download captions

Read the walkthrough

1. This custom Navigation block reads shared site fields.
2. Brand name is a Site Field reference to the source field in Site content.
3. Editing the reference in the content form updates that source value.
4. The header and footer now display the same shared brand name.
5. The custom Post Content block reads this post’s page fields.
6. Its Title is a Page Field reference to the Blog Post title field.
7. Save a new title for this post.
8. The listing reads the updated title. The second post keeps its own title.

Conditional fields

Use Set condition in a field’s menu to show it only when another value matches. The controlling field must precede the dependent field at the same nesting level. Comparisons are Equals (=) and Doesn’t equal (!=).

For example, put a Toggle named show_image before an Image field and show the image field only when the toggle is true. This is a condition you configure; it changes which fields the editor sees. Add {#if show_image} in your block if you also want to hide the image on the published page.

Defaults, instructions, and validation

Set default values in the block’s content, not a default property in its field schema. In files, defaults belong in content.yaml. Use template fallbacks for empty values and an Info field to explain content requirements.

Primo’s browser field editor does not offer required-field enforcement, regex patterns, or text-length limits. Image fields provide maximum file size and maximum dimension options. Schema validation through the CLI checks file structure and value shapes; it does not replace content review or a backend validator for visitor-submitted forms.

fields.yaml

- name: image_help
  type: info
  config:
    info: "Choose a landscape image and add a descriptive alt text."

Derived values and interactions

Use Svelte 5 runes for computed values. In a block with a cards Repeater containing featured (Toggle) and title (Text), you can filter the displayed cards:

component.svelte

<script>
  let featured_cards = $derived((cards ?? []).filter(card => card.featured));
</script>

{#each featured_cards as card}
  <h2>{card.title}</h2>
{/each}

Use $state for interactive state and onclick for event handlers. Do not mix runes with legacy $: statements or export let declarations.

Verify field behavior

Test empty values, long text, missing images, empty repeaters, and optional group content. Add two instances of the block to ensure their section content is independent. Test shared references on more than one page, then publish and check the public result.

Render only trusted content with {@html}. It inserts HTML without escaping; do not assume that imported Markdown or HTML is sanitized.

Next steps

Field types

Look up supported types and value shapes.

Writing blocks

Build responsive blocks with Svelte.