Writing Components - Primo Docs

Write a Svelte component to define how a block looks and behaves. Add fields so editors can change its content. The examples below show code you can adapt for your own blocks.

Watch the workflow

Build a component with an editable field

Watch the workflow in Primo.

Download video · Download captions

Read the walkthrough

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

Components vs Blocks

A Svelte component is the code. A Primo block combines that code with field definitions and default content: Components are pure Svelte code:

Reusable UI elements (Button, Card, Hero)
Accept props and handle logic
No content fields attached
Reusable within a Svelte application; Primo blocks compile independently

Blocks are components with content fields:

Same Svelte component code
Plus editable content fields (text, images, links)
Used specifically in page types and pages
Editors can modify content, not code

When you create a block in Primo, you’re writing a Svelte component and then attaching fields to it. The component code stays the same; fields make it editable.

Component Structure

Every Primo component follows this structure:

<script>
  // 1. Import statements (if needed)
  // 2. Logic that uses fields supplied by Primo
  // 3. Reactive logic
</script>

<!-- 4. HTML markup -->

<style>
  /* 5. Scoped styles */
</style>

Writing Your First Component

Create a block named Button for this example. Its fields and style options are choices you define:

Identify the fields you need

Think about what data your component needs. For a button block:

text: The button text
href: The link destination
variant: The button style (primary, secondary, outline)

Create text as Text, href as URL, and variant as Select with primary, secondary, and outline options. The browser compiler makes these fields available in your component code. For compatibility with older CLI static builders, declare them with $props().

Plan your fields first, then reference them in your template. Set default content in the Content view; in CLI files, use content.yaml.

Add the markup

Write the HTML structure:

<a href={href} class="button" class:primary={variant === "primary"} class:secondary={variant === "secondary"} class:outline={variant === "outline"}>
  {text}
</a>

Style the component

Add scoped styles:

<style>
  .button {
    display: inline-block;
    padding: 0.75rem 1.5rem;
    border-radius: 0.5rem;
    text-decoration: none;
    font-weight: 600;
    transition: all 0.2s;
  }
  
  .primary {
    background: #4f46b6;
    color: white;
  }
  
  .secondary {
    background: #764ba2;
    color: white;
  }
  
  .outline {
    border: 2px solid #4f46b6;
    color: #4f46b6;
    background: transparent;
  }
  
  .button:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  }
</style>

Best Practices

1. Handle Empty Values

Components should work gracefully even with empty fields:

<!-- Good: Provides fallback values -->
<h1>{headline || "Welcome"}</h1>
<p>{subheadline || "Default description"}</p>

<!-- Also good: Conditional rendering -->
{#if headline}
  <h1>{headline}</h1>
{/if}

{#if subheadline}
  <p>{subheadline}</p>
{/if}

2. Use Conditional Rendering

Only show elements when content exists:

{#if image_url}
  <figure>
    <img src={image_url} alt={alt_text} />
    {#if caption}
      <figcaption>{caption}</figcaption>
    {/if}
  </figure>
{/if}

3. Handle Arrays Safely

When working with repeater fields, always check if the array has items:

{#if items && items.length > 0}
  <ul>
    {#each items ?? [] as item}
      <li>{item.name}</li>
    {/each}
  </ul>
{:else}
  <p>No items to display</p>
{/if}

4. Use Scoped Styles

Primo components use scoped styles by default. Use :global() when you need to style child elements:

<style>
  .content :global(h2) {
    font-size: 2rem;
    margin-bottom: 1rem;
  }
  
  .content :global(p) {
    line-height: 1.8;
  }
</style>

5. Make Components Responsive

Always consider mobile devices:

<style>
  .grid {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 2rem;
  }

  @media (max-width: 768px) {
    .grid {
      grid-template-columns: 1fr;
      gap: 1rem;
    }
  }
</style>

6. Create Component Variations

Create Select fields and write the styles for the options you want to offer. Names such as light, dark, primary, and large below are example values; they have no styling effect until your code handles them: Layout variations:

<!-- Field: image_position (Select: "left", "right") -->
<div class="media-block" class:image-right={image_position === "right"}>
  <div class="image">
    {#if image?.url}
      <img src={image.url} alt={image.alt} />
    {/if}
  </div>
  <div class="content">
    <h2>{headline}</h2>
    <p>{description}</p>
  </div>
</div>

<style>
  .media-block {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 2rem;
  }

  .media-block.image-right {
    direction: rtl;
  }

  .media-block.image-right > * {
    direction: ltr;
  }
</style>

Color/theme variations:

<!-- Field: variant (Select: "light", "dark", "primary") -->
<section class="hero variant-{variant}">
  <h1>{headline}</h1>
  <p>{description}</p>
</section>

<style>
  .hero {
    padding: 4rem 2rem;
    text-align: center;
  }

  .variant-light {
    background: #f5f5f5;
    color: #1a1a1a;
  }

  .variant-dark {
    background: #1a1a1a;
    color: #ffffff;
  }

  .variant-primary {
    background: var(--color-primary, #4f46b6);
    color: #ffffff;
  }
</style>

Size variations:

<!-- Field: size (Select: "small", "medium", "large") -->
<button class="btn btn-{size}">
  {label}
</button>

<style>
  .btn {
    padding: 0.5rem 1rem;
    font-size: 1rem;
  }

  .btn-small {
    padding: 0.25rem 0.75rem;
    font-size: 0.875rem;
  }

  .btn-large {
    padding: 0.75rem 1.5rem;
    font-size: 1.25rem;
  }
</style>

One flexible block with variant options is easier to maintain than multiple similar blocks. Editors can adjust layouts without developers creating new components.

Working with Rich Content

Rich Text Fields

When using rich text fields, use {@html} to render HTML:

<div class="rich-text">
  {@html content || ""}
</div>

<style>
  .rich-text :global(h2) {
    font-size: 2rem;
    margin-top: 2rem;
    margin-bottom: 1rem;
  }

  .rich-text :global(p) {
    margin-bottom: 1.5rem;
    line-height: 1.8;
  }

  .rich-text :global(ul), .rich-text :global(ol) {
    margin-bottom: 1.5rem;
    padding-left: 2rem;
  }
</style>

Only use {@html} with trusted content. {@html} inserts HTML without escaping. Do not assume imported Markdown or HTML is sanitized, and do not render untrusted visitor input with it.

Markdown Content

Primo converts Markdown fields to HTML before passing them to your block. Render the result directly; running it through another Markdown parser would process the content twice.

<div class="markdown-content" data-key="markdown_content">
  {@html markdown_content || ""}
</div>

Advanced Patterns

Reactive Statements

Use $derived for computed values based on fields:

<script>
  let displayed_items = $derived((items || []).slice(0, max_items));
  let has_more = $derived((items || []).length > max_items);
</script>

{#each displayed_items as item}
  <div>{item.name}</div>
{/each}

{#if has_more}
  <p>And {items.length - max_items} more...</p>
{/if}

Event Handling

Handle user interactions:

<script>
  function handleClick() {
    // Analytics, tracking, etc.
    console.log('CTA clicked');
  }
</script>

{#if cta_link?.url}
<a href={cta_link.url} onclick={handleClick} class="cta">
  {cta_text}
</a>
{/if}

Conditional Classes

Use dynamic classes for variants:

<div class="card" class:primary={variant === "primary"} class:large={size === "large"}>
  <!-- content -->
</div>

<style>
  .card.primary {
    background: #4f46b6;
    color: white;
  }

  .card.large {
    padding: 2rem;
  }
</style>

Reuse markup inside a block

Blocks compile independently. A relative import such as ./Button.svelte does not automatically resolve another Primo block. Keep reusable markup in a Svelte snippet within the block, or place separate blocks as sections on the page.

{#snippet button(label, url)}
  {#if url}
    <a class="button" href={url}>{label || "Learn more"}</a>
  {/if}
{/snippet}

<section class="hero">
  <h1>{headline}</h1>
  {@render button(cta_text, cta_link?.url)}
</section>

Add headline and cta_text as Text fields and cta_link as a Link field before using this example.

Performance Considerations

Lazy Loading Images

For image-heavy components:

<img src={image_url} alt={alt_text} loading="lazy" />

Optimize Re-renders

Use derived values efficiently:

<script>
  // Good: Only recalculates when items change
  let sorted_items = $derived([...(items || [])].sort((a, b) => a.name.localeCompare(b.name)));
</script>

{#each sorted_items as item}
  <div>{item.name}</div>
{/each}

Testing Your Components

Use the Preview

Primo’s in-browser editor provides instant preview:

Write your component code
Add test content in fields
See changes update in real-time

Test with empty fields, long text, special characters, and edge cases to ensure your component is robust.

Test Different Screen Sizes

Use browser dev tools in the preview to test:

Mobile (320px - 768px)
Tablet (768px - 1024px)
Desktop (1024px+)

Common Patterns

These are Svelte examples for blocks you create, not built-in blocks. Add fields matching the variables each example uses before previewing it.

Card Component

<article class="card">
  {#if image_url}
    <img src={image_url} alt={title} />
  {/if}
  <div class="card-content">
    <h3>{title}</h3>
    {#if description}
      <p>{description}</p>
    {/if}
    {#if link}
      <a href={link} class="card-link">Read More →</a>
    {/if}
  </div>
</article>

<style>
  .card {
    border: 1px solid #e2e8f0;
    border-radius: 0.5rem;
    overflow: hidden;
  }

  .card-content {
    padding: 1.5rem;
  }
</style>

Grid Layout

<section class="grid" style="--columns: {columns}">
  {#each items ?? [] as item}
    <div class="grid-item">{item.content}</div>
  {/each}
</section>

<style>
  .grid {
    display: grid;
    grid-template-columns: repeat(var(--columns), 1fr);
    gap: 2rem;
  }

  @media (max-width: 768px) {
    .grid {
      grid-template-columns: 1fr;
    }
  }
</style>

Accordion Component

<script>
  // Add an items Repeater with title and content Text subfields.
  let open_index = $state(null);
  
  function toggle(index) {
    open_index = open_index === index ? null : index;
  }
</script>

<div class="accordion">
  {#each items ?? [] as item, index}
    <div class="accordion-item">
      <button class="accordion-header" aria-expanded={open_index === index} onclick={() => toggle(index)}>
        {item.title}
        <span class="icon">{open_index === index ? '−' : '+'}</span>
      </button>
      {#if open_index === index}
        <div class="accordion-content">
          {item.content}
        </div>
      {/if}
    </div>
  {/each}
</div>

Next Steps

Working with Fields

Learn how to attach content fields to your components.

Using the Component Library

Organize and reuse components across sites.

Field Types Reference

Complete reference of all available field types.

Your First Site

See components in action with a complete site example.

The best components are simple, focused, and reusable. Start with basic functionality, then add complexity only when needed.

​Watch the workflow

​Build a component with an editable field

​Components vs Blocks

​Component Structure

​Writing Your First Component

​Best Practices

​1. Handle Empty Values

​2. Use Conditional Rendering

​3. Handle Arrays Safely

​4. Use Scoped Styles

​5. Make Components Responsive

​6. Create Component Variations

​Working with Rich Content

​Rich Text Fields

​Markdown Content

​Advanced Patterns

​Reactive Statements

​Event Handling

​Conditional Classes

​Reuse markup inside a block

​Performance Considerations

​Lazy Loading Images

​Optimize Re-renders

​Testing Your Components

​Use the Preview

​Test Different Screen Sizes

​Common Patterns

​Card Component

​Grid Layout

​Accordion Component

​Next Steps

Working with Fields

Using the Component Library

Field Types Reference

Your First Site

Watch the workflow

Build a component with an editable field

Components vs Blocks

Component Structure

Writing Your First Component

Best Practices

1. Handle Empty Values

2. Use Conditional Rendering

3. Handle Arrays Safely

4. Use Scoped Styles

5. Make Components Responsive

6. Create Component Variations

Working with Rich Content

Rich Text Fields

Markdown Content

Advanced Patterns

Reactive Statements

Event Handling

Conditional Classes

Reuse markup inside a block

Performance Considerations

Lazy Loading Images

Optimize Re-renders

Testing Your Components

Use the Preview

Test Different Screen Sizes

Common Patterns

Card Component

Grid Layout

Accordion Component

Next Steps