@if

Display content based on dynamic conditions

Conditional statements in Elements allow you to control when content is displayed based on certain conditions. Using @if, @elseif, and @else, you can define different outcomes depending on the values of variables. This is useful for showing or hiding content based on user settings, mode (edit or preview), or other dynamic conditions.

Syntax

@if(condition)
    <!-- Content shown when condition is true -->
@endif

With else if and else branches:

@if(condition)
    <!-- Content for first condition -->
@elseif(otherCondition)
    <!-- Content for second condition -->
@else
    <!-- Fallback content -->
@endif

Template @if accepts a single condition only. You can negate it with ! (e.g. @if(!edit)), but you cannot use boolean operators (&&, ||) or comparison operators (==, !=, >, <, >=, <=) inside a template @if. Doing so triggers a lexer error (invalid syntax). See Combining Conditions for the supported alternatives.

This restriction applies only to template @if. The visible and enabled expressions in properties.json do support boolean and comparison operators.

Block-Level Conditionals

Basic If Statement

Display content when a switch or boolean property is true:

@if(showSubtitle)
    <p class="subtitle">{{subtitle}}</p>
@endif

If Not Statement

Use the ! operator to check if something is false:

@if(!edit)
    We're in preview mode or the site is Published.
@endif

Multiple Conditions with Else If

Chain multiple conditions before falling back to else:

@if(edit)
    We're in edit mode
@elseif(preview)
    And now in preview
@elseif(showAlternate)
    The alternate option is enabled
@else
    Default content
@endif

Edit/Preview Mode Detection

Elements provides built-in edit and preview variables:

@if(edit)
    Visible in Edit mode (inside Elements)
@elseif(preview)
    Visible in local preview (in Safari).
@else
    Visible when Published.
@endif

Inline Conditionals

Conditionals can also be used inline within HTML attributes. This is particularly useful for dynamic class names and attribute values.

Dynamic Class Names

Apply classes conditionally based on properties:

<div class="slide @if(image::isFirst) slide-active @else slide-hidden @endif">
    <img src="{{image.src}}" />
</div>

Multiple Conditional Classes

Chain multiple inline conditions for complex class logic:

<li class="item @if(page.isTopLevel) top-level @elseif(page.isSecondLevel) sub-menu @elseif(page.isThirdLevel) third-level @endif">
    {{page.title}}
</li>

Conditional Attributes

Add or remove attributes based on conditions:

<a 
    href="{{page.url}}"
    @if(page.openInNewWindow)
    target="_blank"
    @endif
>
    {{page.title}}
</a>

Conditional Image Attributes

Apply different behaviors based on settings:

<img
    src="{{image.src}}"
    alt="{{image.alt}}"
    @if(imageProtection)
    oncontextmenu="return false"
    ondragstart="return false"
    @endif
    @if(imageLazyLoading)
    loading="lazy"
    @endif
    @if(wantsFetchPriority)
    fetchpriority="{{imageFetchPriority}}"
    @endif
/>

Conditional Visibility Styles

Hide elements in preview/published mode:

<div 
    @if(!edit)
    style="display: none"
    @endif
    class="modal-backdrop"
>
    <!-- Modal content -->
</div>

Nested Conditionals

Conditionals can be nested for complex logic:

@if(page.hasPages)
    <ul>
        @each(subPage in page.pages)
            @if(subPage.isVisible)
                <li>{{subPage.title}}</li>
            @endif
        @endeach
    </ul>
@endif

Combining with @each

Use conditionals within loops for filtered rendering:

@each(page in pages)
    @if(page.isFolder)
        @include("folder_template")
    @else
        @include("link_template")
    @endif
@endeach

Common Patterns

Fallback Content

Show a placeholder when no content exists:

@if(!hasImage)
    <img src="{{sharedAssetPath}}/images/placeholder.png" alt="Placeholder" />
@else
    <img src="{{image.src}}" alt="{{image.alt}}" />
@endif

Feature Toggles

Enable or disable component features:

@if(showIcon)
    <span class="icon">
        @include("icon")
    </span>
@endif

Conditional Includes

For conditional template includes, consider using @includeIf for cleaner syntax:

@includeIf(wantsLightbox, template: "lightbox")

Combining Conditions

Because a template @if only accepts a single condition, you cannot write expressions like @if(edit && hidePreview) or @if(count > 0). Use one of the following approaches instead.

Nest separate @if directives

For "AND" logic, nest one @if inside another:

@if(hidePreview)
    @if(!edit)
        <!-- Shown only when hidePreview is on AND we're not in edit mode -->
    @endif
@endif

Push the logic into CSS

Emit marker classes from independent @if directives, then combine them with a CSS selector. This is the recommended pattern for show/hide behaviour, as it works reliably in edit, preview, and published modes:

<div class="preview-bar @if(hidePreview) is-hideable @endif @if(!edit) is-live @endif">
    <!-- bar content -->
</div>

/* Hide the bar only when both markers are present
   (hide-preview switch is on AND we're outside the editor) */
.preview-bar.is-hideable.is-live {
    display: none;
}

Compute a boolean in hooks.js

For comparisons or more complex logic, calculate a single boolean in the hooks file and pass it to the template, then test that one value:

// hooks.js
exports.transformHook = (rw) => {
    rw.setProps({
        hasManyItems: rw.props.items.length > 2,
    });
};

@if(hasManyItems)
    <!-- Shown when there are more than two items -->
@endif

Best Practices

1. One condition per @if - Template @if takes a single condition (optionally negated with !). For combined or comparison logic, nest @if directives, combine marker classes in CSS, or compute a boolean in the hooks file. See Combining Conditions.
2. Keep conditions simple - For complex logic like string comparisons, use the hooks file to compute boolean values and pass them to the template.
3. Use meaningful property names - Boolean properties should have clear names like showIcon, enableLazyLoading, or hasImage.
4. Prefer @includeIf for conditional includes - Instead of wrapping @include in @if, use @includeIf for cleaner templates.
5. Only non-responsive controls work in conditionals - Responsive controls cannot be used directly in @if statements.

Related

• Combining Conditions - Working around the single-condition limit
• @includeIf - Conditional template includes
• Hooks File - For complex conditional logic
• properties.json visible - Where boolean and comparison operators are supported