Skip to content

Instance Components

Need a new reusable block but don't want to wait for a deployment? Instance components let authorized admin users create Hyvä CMS components right from the Liveview Editor. They live in the database instead of a module's components.json file.

Reach for instance components when you need a site-specific reusable block or a controlled variation in a hurry. For long-lived design-system components, code-defined components are still usually the better foundation.

When to Use Instance Components

Instance components are built for straightforward, presentational content. Think of an "About Us" employee highlight, a promo strip, or a trust-badge group: a fixed layout with a handful of editable fields. That is exactly what they are good at.

Instance components are deliberately not a substitute for application logic. The template syntax renders field values and handles basic conditionals and loops, and that is the ceiling. There is no support for a field value driving a CSS class, a style attribute, or any other dynamic behaviour, and we do not plan to add it.

That limit is on purpose, for two reasons:

  • Security. Letting field values flow into class or style attributes turns a content tool into an injection surface. Keeping output escaped and presentational keeps the builder safe to hand to non-developers.
  • Maintainability. Logic that lives in a database row is hard to review, test, and version alongside the rest of your code. It tends to drift and surprise people later.

Choosing between an instance component and a code component

If the idea is "a fixed layout with a few editable fields," an instance component is a great fit. The moment you find yourself wanting a field to change styling, toggle structural behaviour, or carry conditional logic beyond a simple show/hide, build it as a code-defined component instead. Advanced components belong in code, where they can be reviewed, tested, and deployed properly.

For Merchants and Admin Users: Creating Instance Components in the Editor

To create an instance component, open the editor menu and choose Instance Components. From there you can create, edit, deactivate, or delete instance components.

An instance component has:

  • Name
  • Identifier
  • Category
  • Optional description
  • Optional availability restrictions by content type
  • Icon
  • Active or inactive status
  • Editable fields
  • HTML template

The identifier becomes the component key in the editor, prefixed with instance/. For example, an identifier of promo-strip appears as instance/promo-strip.

Editing an existing instance component changes every current use of that component across the site. Deactivate a component when it should no longer be added in the editor.

The icon can be an emoji, with optional background and border colors, or a module image path, so instance components are easy to recognize in the component picker.

Instance Component Field Types

The visual builder for instance components supports common field types:

  • Text, textarea, rich text, HTML, and URL
  • Image and link
  • Boolean, color, date, date and time, number, and range
  • Select, multiselect, and searchable select

Text-like fields can be marked as translatable. Select fields can define options. Supported field types can also define default values.

Advanced users can switch to the JSON editor for the raw field declaration.

Instance Component Template Syntax

The instance component template editor uses a lightweight variable syntax to render field values into HTML. The example below renders a title, a conditional image, and a conditional link:

<section class="promo-strip">
    <h2>{title}</h2>
    {#if image}
        <img src="{image.src}" alt="{image.alt}">
    {/if}
    {#if link}
        {link}
    {/if}
</section>

Supported template syntax includes:

  • {field} for field rendering
  • {field.property} for nested values such as image or link data
  • {raw:field} for escaped raw values without field-specific rendering
  • {#if field}...{/if} and {#if field}...{#else}...{/if}
  • {#foreach items as item}...{/foreach}
  • \{ and \} for literal braces

Image, link, and rich text fields have field-specific renderers. All other values are escaped before output.

Instance Component Permissions (Magento ACL)

Instance component actions are protected by Magento ACL under:

Content > Elements > Hyvä CMS Instance Components

Available permissions:

  • View
  • Save
  • Delete

Exporting and Importing Instance Components

The Import & Export feature can include instance components during export and import. This matters when content uses instance/... components, because the target environment needs the component definition as well as the page or block content.

On import, instance component identifiers can be remapped when content is imported as new, and component references in the imported content are updated to match.

For Developers

Instance components are merged into the normal Hyvä CMS component registry; see Component Discovery in Architecture Overview for how they're loaded alongside module-defined components.

Instance components are not a substitute for code review

The instance component builder is a controlled admin feature. Reserve unrestricted HTML and template access for trusted users, and treat instance components as content rather than reviewed, versioned application code.