Conditional Rendering

Learn about the various methods for conditionally rendering content in Aurelia 2, with detailed explanations and examples.

Conditional rendering allows you to dynamically show or hide parts of your view based on your application's state. Aurelia 2 provides three primary directives for conditional rendering, each suited for different scenarios.

Quick Reference

Directive	Use Case	DOM Behavior	Performance
if.bind	Simple true/false conditions	Adds/removes elements	Best for infrequent changes
show.bind	Toggle visibility	Hides/shows elements	Best for frequent changes
switch.bind	Multiple conditions	Adds/removes elements	Best for enum-like values

Using if.bind

The if.bind directive conditionally adds or removes elements from the DOM based on a boolean expression. When the expression is false, Aurelia completely removes the element and its descendants, cleaning up resources, events, and custom elements.

Basic Usage

<div if.bind="isLoading">Loading...</div>
<div if.bind="user.isAuthenticated">Welcome back, ${user.name}!</div>

If/Else Structures

Use else immediately after an if.bind element to create branching logic:

<div if.bind="user.isAuthenticated">
  Welcome back, ${user.name}!
</div>
<div else>
  Please log in to continue.
</div>

Else-If Chains

You can chain additional conditions by combining else and if.bind on the same element:

<div if.bind="status === 'loading'">
  Loading...
</div>
<div else if.bind="status === 'error'">
  Something went wrong.
</div>
<div else if.bind="status === 'empty'">
  No results found.
</div>
<div else>
  Content is ready.
</div>

This also works on direct custom elements, not just native elements or explicit <template> nodes:

<loading-screen if.bind="status === 'loading'"></loading-screen>
<error-screen else if.bind="status === 'error'"></error-screen>
<empty-state else if.bind="status === 'empty'"></empty-state>
<results-grid else></results-grid>

Ordering Rules for else if

else if is still an else chain. The branch rules are:

• else must belong to the immediately preceding conditional branch.

• else must appear before if.bind on the same element.

• Plain attributes and non-template-controller custom attributes may appear between else and if.bind on that same element.

• Another template controller between else and if.bind means the attributes do not form an else if branch.

• A plain else branch ends the chain. Another else after that is invalid.

Valid examples:

<div if.bind="step === 0">A</div>
<div else class="branch" if.bind="step === 1">B</div>
<div else marker if.bind="step === 2">C</div>
<div else>D</div>

A controller-bearing structure between sibling branches breaks the chain:

<div if.bind="step === 0">A</div>
<p repeat.for="item of items">${item}</p>
<div else>B</div>

This same-element combination is unsupported as else if because repeat separates the two template controllers:

<div if.bind="step === 0">A</div>
<div else repeat.for="item of items" if.bind="step === 1">B</div>

Async Branch Transitions

If a leaving branch has async deactivation or an entering branch has async activation, Aurelia waits for those lifecycle promises as part of the branch swap.

In practice:

• the current branch begins leaving first

• the replacement branch starts only after the previous branch has finished its async leave work

• a branch superseded during async attachment begins leaving immediately, with later branch work queued behind its teardown

• once the replacement branch starts attaching, its DOM may already be present before the async attaching() promise resolves

If you assert intermediate DOM state in tests, account for those lifecycle phases rather than assuming the entire swap happens in a single microtask.

Caching Behavior

By default, if.bind caches views and view models for performance. Disable caching when you need fresh instances:

<custom-element if="value.bind: canShow; cache: false"></custom-element>

With caching disabled, Aurelia deactivates and disposes a branch when a conditional change removes it. Returning to that branch creates a new view and view model.

When to Use: Use if.bind when elements change infrequently and you want to completely remove them from the DOM to save memory and improve performance.

Using show.bind

The show.bind directive toggles element visibility without removing them from the DOM. This is equivalent to setting display: none in CSS.

Basic Usage

<div show.bind="isDataLoaded">Data loaded successfully!</div>
<div show.bind="!isLoading">Content is ready</div>

hide.bind (inverse of show.bind)

hide is an alias of show with inverted logic:

<div hide.bind="isHidden">Hidden when true</div>

This is equivalent to:

<div show.bind="!isHidden">Hidden when true</div>

When to Use show.bind vs if.bind

<!-- Use show.bind for frequent toggles -->
<div show.bind="isExpanded">
  <expensive-component></expensive-component>
</div>

<!-- Use if.bind for infrequent changes -->
<admin-panel if.bind="user.isAdmin"></admin-panel>

When to Use: Use show.bind when you need to frequently toggle visibility and want to preserve element state, bindings, and avoid re-initialization costs.

Using switch.bind

The switch.bind directive handles multiple conditions elegantly, similar to a JavaScript switch statement. It's ideal for enum values or when you have several mutually exclusive conditions.

Basic Usage

// Status.ts
enum OrderStatus {
  Received   = 'received',
  Processing = 'processing',
  Dispatched = 'dispatched',
  Delivered  = 'delivered'
}

<!-- order-status.html -->
<template switch.bind="orderStatus">
  <span case="received">Order received</span>
  <span case="processing">Processing your order</span>
  <span case="dispatched">On the way</span>
  <span case="delivered">Delivered</span>
  <span default-case>Unknown status</span>
</template>

Grouping Cases

Handle multiple values with a single case:

<template switch.bind="orderStatus">
  <span case.bind="['received', 'processing']">
    Order is being processed
  </span>
  <span case="dispatched">On the way</span>
  <span case="delivered">Delivered</span>
</template>

Fall-Through Behavior

Enable fall-through to show multiple cases:

<template switch.bind="orderStatus">
  <span case="received" fall-through="true">Order received</span>
  <span case="processing">Processing your order</span>
</template>

Fall-through is false by default. Set fall-through="true" or fall-through.bind="true" to enable it.

Advanced Techniques

Dynamic Switch Expressions

Use computed expressions with switch.bind:

<template repeat.for="num of numbers">
  <template switch.bind="true">
    <span case.bind="num % 15 === 0">FizzBuzz</span>
    <span case.bind="num % 3 === 0">Fizz</span>
    <span case.bind="num % 5 === 0">Buzz</span>
    <span default-case>${num}</span>
  </template>
</template>

Conditional Slot Projection

Combine switch.bind with slots for dynamic content projection:

<template as-custom-element="status-card">
  <au-slot name="content"></au-slot>
</template>

<status-card>
  <template au-slot="content" switch.bind="status">
    <div case="loading">Loading...</div>
    <div case="error">Something went wrong</div>
    <div case="success">Operation completed</div>
  </template>
</status-card>

Nested Switches

Handle complex conditional logic with nested switches:

<template switch.bind="userRole">
  <div case="admin">
    <template switch.bind="adminSection">
      <admin-users case="users"></admin-users>
      <admin-settings case="settings"></admin-settings>
      <admin-dashboard default-case></admin-dashboard>
    </template>
  </div>
  <user-dashboard case="user"></user-dashboard>
  <guest-welcome default-case></guest-welcome>
</template>

Performance Guidelines

Choosing the Right Directive

• Frequent toggles: Use show.bind to avoid DOM manipulation overhead

• Infrequent changes: Use if.bind to remove elements and save memory

• Multiple conditions: Use switch.bind for cleaner, more maintainable code

Optimization Tips

<!-- Good: Group related conditions -->
<template switch.bind="appState">
  <loading-screen case="loading"></loading-screen>
  <error-screen case="error"></error-screen>
  <main-content case="ready"></main-content>
</template>

<!-- Avoid: Multiple separate if statements -->
<loading-screen if.bind="appState === 'loading'"></loading-screen>
<error-screen if.bind="appState === 'error'"></error-screen>
<main-content if.bind="appState === 'ready'"></main-content>

Important Restrictions

Case Usage Rules

The case attribute must be a direct child of switch.bind:

<!-- ✅ Correct -->
<template switch.bind="status">
  <span case="active">Active</span>
</template>

<!-- ❌ Incorrect: case not direct child -->
<template switch.bind="status">
  <div if.bind="someCondition">
    <span case="active">Active</span>
  </div>
</template>

Default Case Placement

Place default-case as the last option for best practices:

<template switch.bind="status">
  <span case="received">Received</span>
  <span case="processing">Processing</span>
  <span default-case>Unknown</span> <!-- Last -->
</template>