Field Types

Fields are what make blocks editable. You attach fields to your blocks, and editors can fill them in without touching code. This reference covers Primo’s built-in field types. Variable names and block designs in the examples are choices you define; create the matching fields before using the code.

Fields can be added to three places:

Sites - Site-wide content (logo, navigation, footer, etc.)
Page Types - Content each page stores, such as a title, author, or article body
Blocks - Section-level content (headlines, images, descriptions, etc.)

Most field types work the same in all contexts, with some exceptions noted below.

Type names in files

Field definitions use name, label, type, and optional config. Use lowercase type IDs: text, rich-text, markdown, number, date, select, switch (Toggle), slider, image, icon, link, url, site-field, page-field, page, page-list, repeater, group, and info. Nested Group and Repeater fields use subfields. Defaults belong in content.yaml, not a default or required property on the field. See file examples.

Text Fields

Text

Text input that automatically grows to accommodate content.Use for:

Headlines and titles
Button labels
Short descriptions
Names

Component usage:

<h1>{headline}</h1>
<p>{description}</p>

Rich Text

Rich text editor with formatting controls. It supplies HTML to your block.Use for:

Article content
Descriptions with formatting
Long-form content
Any text needing formatting

Component usage:

<div class="content">
  {@html content}
</div>

Rich text fields output HTML. Always use {@html} in your component to render it. To style the HTML content, use :global() in your CSS to target elements inside the rendered HTML. Use a unique class name on the wrapper to avoid affecting other styles on the page.

Markdown

Markdown editor for formatted text.Use for:

Documentation
Blog posts
README content
Developer-friendly content

Component usage:

<!-- Primo processes markdown automatically -->
<div class="markdown-content">
  {@html content}
</div>

<style>
  /* Use :global() to style rendered HTML */
  /* Use a unique class to avoid affecting other elements */
  .markdown-content :global(h1) {
    font-size: 2rem;
  }
  .markdown-content :global(p) {
    margin-bottom: 1rem;
  }
</style>

Number and date fields

Number

Numeric input that stores a number. The implementation parses values with parseFloat, so values are not restricted to integers.Use for:

Quantities
Counts
Whole number ratings
Numeric values

Component usage:

<p>Quantity: {quantity}</p>
<p>Rating: {rating}/5</p>

Date

Date picker that outputs dates in YYYY-MM-DD format.Use for:

Publication dates
Event dates
Deadlines
Any calendar dates

Component usage:

<!-- Raw YYYY-MM-DD format -->
<time datetime={publish_date}>{publish_date}</time>

<!-- Formatted for display -->
<time datetime={publish_date}>
  {new Date(publish_date).toLocaleDateString("en-US", { timeZone: "UTC" })}
</time>

<!-- Custom formatting -->
<time datetime={publish_date}>
  {new Date(publish_date).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
    timeZone: 'UTC'
  })}
</time>

The Date input uses YYYY-MM-DD format (e.g., “2024-01-15”). Values are strings; resolved references or imported dates can include an ISO timestamp such as “2024-01-15T00:00:00Z”. Use JavaScript’s new Date() constructor with an explicit UTC display time zone for date-only strings, which are parsed as UTC. Without that option, users west of UTC can see the previous day. Quote date values in YAML, such as publish_date: "2026-10-11", so parsers keep them as strings. A Date field does not schedule publication. Use the raw value for the datetime attribute in <time> elements.

Selection Fields

Select

Dropdown menu for selecting one option from a list.Use for:

Categories
Variants
Status options
Single-choice selections

Component usage:

<span class="category">{category}</span>

Options:Each option in a Select field has three properties:

value: The actual value stored (used in your code)
label: Display text shown to editors
icon: Optional icon identifier (from Iconify)

The first option in the list is used as the default value.

Toggle

Boolean toggle switch for on/off options.Use for:

Feature toggles
Boolean settings
Show/hide options
Enable/disable states

Component usage:

{#if show_cta}
  <button>Click me</button>
{/if}

Slider

Slider for selecting numeric values.Use for:

Opacity values
Percentage selections
Adjustable numeric settings

Component usage:

<div style="opacity: {opacity}">
  Content with adjustable opacity
</div>

Media Fields

Image

Image upload and selection field. Returns an object with url and alt properties.Use for:

Photos
Graphics
Custom icons
Any visual content

Component usage:

{#if image?.url}
  <img src={image.url} alt={image.alt} />
{/if}

Options (both optional):

Max Size MB: Maximum file size in megabytes
Max Width or Height: Maximum dimension (width or height) in pixels

The image field includes a Description input for alt text. Editors should fill this out, and developers should use image.alt in their components for accessibility.

Icon

Icon picker for selecting icons from Iconify. Returns an SVG string.Use for:

Feature icons
UI elements
Decorative icons
Navigation icons

Component usage:

<!-- Wrap in a div for styling with font-size and color -->
<div class="icon">
  {@html icon}
</div>

<style>
  .icon {
    font-size: 2rem;
    color: var(--color-primary, #4f46b6);
  }
</style>

For UI icons that should stay consistent across your site, consider creating a site field containing icon values. This lets you update icons site-wide from one place instead of editing individual blocks.

Link Fields

Link

Link field for both internal and external links. Returns an object with url and label properties.Use for:

Navigation items
Call-to-action buttons
Any clickable links

Component usage:

{#if link?.url}
  <a href={link.url}>{link.label || "Learn more"}</a>
{/if}

URL

Simple URL input field.Use for:

External URLs
Web addresses
API endpoints
Any URL string

Component usage:

{#if website_url}
  <a href={website_url} target="_blank" rel="noopener noreferrer">Visit website</a>
{/if}

Relational Fields

Site Field

Connect a block or page type field to a field defined on the site. It receives the source field’s value, whether that value is text, an image, or structured content.Use for:

Displaying site-wide content in blocks
Reusing global content across pages
Referencing branding elements

Component usage:

<!-- If the site has a "logo" image field -->
{#if logo?.url}
  <img src={logo.url} alt={logo.alt || ""} />
{/if}

<!-- If the site has a "company_name" text field -->
<h1>{company_name}</h1>

Available in page types and blocks to reference site-wide content.

When you edit a site field from the block form view, it updates the value site-wide across all blocks that reference it. Site fields cannot be edited inline on the page yet.

Page Field

Connect a block field to a field defined on the current page’s type. It receives that page’s value.Use for:

Displaying page title in blocks
Showing page metadata in blocks

Component usage:

<!-- If the page has a "title" text field -->
<h1>{title}</h1>

<!-- If the page has a "featured_image" image field -->
{#if featured_image?.url}
  <img src={featured_image.url} alt={featured_image.alt || ""} />
{/if}

Available in blocks to reference page-level content.

When you edit a page field from the block form view, it updates the value for that specific page across all blocks that reference it. For example, updating featured_image changes every place your code uses that page field. Header images, social metadata, and article lists must each be connected explicitly.

Page fields cannot be edited inline on the page yet.

Page

Let an editor choose one page of a configured page type. Create that page type first; names such as Person and Blog Post below are examples.Use for:

Article author (Person page type)
Featured article (Blog Post page type)
Related pages

Component usage:

<!-- Access page fields like title or custom fields -->
{#if author?._meta?.url}
  <a href={author._meta.url}>
    <h3>{author.name || author._meta.name}</h3>
    <p>{author.bio}</p>
  </a>
{/if}

The _meta property provides:

_meta.url: Page URL for linking
_meta.slug: Page slug
_meta.name: Page name

Options:

Page Type: Required. Specifies which page type to select from (e.g., “Person”, “Blog Post”)

Page List

Supply all pages of a configured page type to your block code. Your code renders the list; editors do not choose individual entries in this field.Use for:

Team member listings (all Person pages)
Blog index (all Blog Post pages)
Automatic page lists

Component usage:

<div class="team">
  {#each members ?? [] as member}
    <a href={member._meta.url}>
      <h3>{member.name}</h3>
      <p>{member.title}</p>
    </a>
  {/each}
</div>

Options:

Page Type: Required. Specifies which page type to output (e.g., “Person”, “Blog Post”)

If you want editors to choose specific pages, use a Repeater field with nested Page fields instead. To exclude selected pages, add a Repeater containing a Page field and filter the Page List in your block code; see the example below.

Structured Fields

Repeater

Repeatable group of fields.Use for:

Feature lists
Testimonials
FAQ items
Image galleries
Card grids

Component usage:

<ul>
  {#each features ?? [] as feature}
    <li>
      {#if feature.icon?.url}
        <img src={feature.icon.url} alt={feature.icon.alt || ""} />
      {/if}
      <h3>{feature.title}</h3>
      <p>{feature.description}</p>
    </li>
  {/each}
</ul>

<!-- Or with destructuring -->
<ul>
  {#each features ?? [] as { icon, title, description }}
    <li>
      {#if icon?.url}
        <img src={icon.url} alt={icon.alt || ""} />
      {/if}
      <h3>{title}</h3>
      <p>{description}</p>
    </li>
  {/each}
</ul>

Avoid naming your loop variable the same as a nested field. For example, if you have a nested link field, use {#each links ?? [] as item} instead of {#each links ?? [] as link} to prevent confusion when accessing item.link.url.

A “Features” block might use a repeater named features with fields: title (Text), description (Text), and icon (Image). Editors can add multiple features, and each gets the same set of fields.

Group

Group of related fields displayed together.Use for:

Contact details (email + phone + address)
Card content (title + description + cta_link)
Author info (name + bio + photo)

Component usage:

<div class="author">
  {#if author?.photo?.url}
    <img src={author.photo.url} alt={author.photo.alt || ""} />
  {/if}
  <h3>{author?.name}</h3>
  <p>{author?.bio}</p>
</div>

Utility Fields

Info

Display-only field for showing helpful information to editors. Supports Markdown formatting and does not store any data—it only displays content in the editor interface.Use for:

Instructions for complex fields
Explanatory notes about content requirements
Documentation for editors

Consider combining Info fields with conditions to show context-specific help. For example, create a Select option named “Custom Layout” and an Info field explaining the options you implement for it. Add a condition to show that help when the option is selected.

Field Configuration

All fields share these base properties:

Type: The field type (text, image, select, etc.)
Label: Display name shown to editors
Key: The variable name used in your component code

Field-Specific Options

Some field types have additional configuration options: Select:

Options: Array of choices, each with value, label, and optional icon

Image:

Max Size (MB): Maximum file size in megabytes
Max Dimension (px): Maximum dimension (width or height) in pixels

Page / Page List:

Page Type: The type editors choose from (Page) or the type whose pages are returned (Page List)

Conditional Display

Fields can be conditionally shown or hidden based on other field values. Conditions are primarily designed for Select and Toggle fields, but also work with Text, URL, and Number fields. When you add a condition (“Show if”):

Field: Select which field to check (must be a preceding field at the same level)
Comparison: Choose “Equals” or “Doesn’t equal” (≠)
Value: The value to compare against

Conditions show relevant form fields based on other selections; they do not hide content in the published page. Add a matching condition in your block code when needed. For example, to show an image field only when a “Show Image” toggle is enabled, the “Show Image” toggle must come first in the field list, then the image field below it with the condition. Fields can only reference fields that appear before them in the list.

Best Practices

1. Choose the Right Field Type

Match field types to their purpose:

✅ Text for headlines
✅ Rich Text for formatted content
✅ Image for photos
✅ Select for categories
❌ Text for long articles (use Rich Text)
❌ Number for phone numbers (use Text)

2. Handle empty values

The browser compiler supplies your defined fields as block props. Handle empty or missing values with fallbacks or conditional rendering:

<!-- Good: Handles empty values -->
{#if headline}
  <h1>{headline}</h1>
{/if}

{#if show_cta}
  <button>Click me</button>
{/if}

<!-- Also good: Use default values with OR -->
<h1>{headline || "Welcome"}</h1>

3. Use Helpful Labels

Clear labels help editors understand fields:

✅ “Featured Image”
✅ “Publication Date”
✅ “Author Name”
❌ “Field 1”
❌ “Data”

4. Add an Info field

Use an Info field to guide editors:

Field: “Featured Image” Example Info field content: “Choose a landscape image for the post header and add descriptive alt text.” Describe social-sharing use only if your code connects the image to social metadata.

Field Combinations

These are examples you can build from the field types above, not predefined block schemas. Create the listed fields and any referenced page types before using the code.

Common Patterns

Hero Block:

headline (Text)
subheadline (Text)
cta (Link)
background_image (Image, optional)

<section>
  {#if background_image?.url}
    <img src={background_image.url} alt={background_image.alt} class="background" />
  {/if}
  <h1>{headline}</h1>
  <p>{subheadline}</p>
  {#if cta?.url}
    <a href={cta.url}>{cta.label}</a>
  {/if}
</section>

Card Block:

title (Text)
description (Rich Text)
image (Image, optional)
link (Link, optional)

<div class="card">
  {#if image?.url}
    <img src={image.url} alt={image.alt} />
  {/if}
  <h3>{title}</h3>
  <div class="description">{@html description}</div>
  {#if link?.url}
    <a href={link.url}>{link.label || "Learn more"}</a>
  {/if}
</div>

Feature List:

features (Repeater) with:
- title (Text)
- description (Text)
- icon (Image, optional)

<ul class="features">
  {#each features ?? [] as feature}
    <li>
      {#if feature.icon?.url}
        <img src={feature.icon.url} alt={feature.icon.alt || ""} />
      {/if}
      <h3>{feature.title}</h3>
      <p>{feature.description}</p>
    </li>
  {/each}
</ul>

Employees of the Month (editor selects):

employees (Repeater) with:
- employee (Page, limited to “Person” page type)

<div class="employees">
  {#each employees ?? [] as { employee }}
    {#if employee?._meta?.url}
      <a href={employee._meta.url}>
        <h3>{employee.name || employee._meta.name}</h3>
        <p>{employee.title}</p>
      </a>
    {/if}
  {/each}
</div>

Filtered Page List (selection by exclusion):

all_team (Page List, “Person” page type)
excluded_members (Repeater) with:
- member (Page, limited to “Person” page type)

<script>
  // Add both fields before using this block. Compare full URLs so pages
  // with the same slug under different parents remain distinct.
  let displayed_team = $derived((all_team ?? []).filter(person =>
    !(excluded_members ?? []).some(({ member }) => member?._meta?.url === person._meta.url)
  ));

</script>

<div class="team">
  {#each displayed_team as person}
    <a href={person._meta.url}>
      <h3>{person.name}</h3>
      <p>{person.title}</p>
    </a>
  {/each}
</div>

Start with simple field types (Text, Image, Link) and add complexity (Repeaters, Groups) as you need it. Most blocks only need a few well-chosen fields.

Next Steps

Working with Fields

Learn how to add fields to your components.

Writing Components

See how fields work in component code.

Defining Page Types

Use fields in page type configuration.

Building from Scratch

See fields in action with real examples.

Getting Started

Building Sites

CLI

Collaboration

Content Management

Dashboard

Reference

Type names in files

Text Fields

Number and date fields

Selection Fields

Media Fields

Link Fields

Relational Fields

Structured Fields

Utility Fields

Field Configuration

Field-Specific Options

Conditional Display

Best Practices

1. Choose the Right Field Type

2. Handle empty values

3. Use Helpful Labels

4. Add an Info field

Field Combinations

Common Patterns

Next Steps

Working with Fields

Writing Components

Defining Page Types

Building from Scratch

​Type names in files

​Text Fields

​Number and date fields

​Selection Fields

​Media Fields

​Link Fields

​Relational Fields

​Structured Fields

​Utility Fields

​Field Configuration

​Field-Specific Options

​Conditional Display

​Best Practices

​1. Choose the Right Field Type

​2. Handle empty values

​3. Use Helpful Labels

​4. Add an Info field

​Field Combinations

​Common Patterns

​Next Steps

Working with Fields

Writing Components

Defining Page Types

Building from Scratch

Type names in files

Text Fields

Number and date fields

Selection Fields

Media Fields

Link Fields

Relational Fields

Structured Fields

Utility Fields

Field Configuration

Field-Specific Options

Conditional Display

Best Practices

1. Choose the Right Field Type

2. Handle empty values

3. Use Helpful Labels

4. Add an Info field

Field Combinations

Common Patterns

Next Steps