All pages
Powered by GitBook
1 of 1

Loading...

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

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.

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

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

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

hide is an alias of show with inverted logic:

This is equivalent to:

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.

Handle multiple values with a single case:

Enable fall-through to show multiple cases:

Use computed expressions with switch.bind:

Combine switch.bind with slots for dynamic content projection:

Handle complex conditional logic with nested switches:

  • 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

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

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

for cleaner, more maintainable code

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

Basic Usage

If/Else Structures

Caching Behavior

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

Basic Usage

hide.bind (inverse of show.bind)

When to Use show.bind vs if.bind

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

Basic Usage

Grouping Cases

Fall-Through Behavior

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

Advanced Techniques

Dynamic Switch Expressions

Conditional Slot Projection

Nested Switches

Performance Guidelines

Choosing the Right Directive

Optimization Tips

Important Restrictions

Case Usage Rules

Default Case Placement

<div if.bind="isLoading">Loading...</div>
<div if.bind="user.isAuthenticated">Welcome back, ${user.name}!</div>
<div if.bind="user.isAuthenticated">
  Welcome back, ${user.name}!
</div>
<div else>
  Please log in to continue.
</div>
<custom-element if="value.bind: canShow; cache: false"></custom-element>
<div show.bind="isDataLoaded">Data loaded successfully!</div>
<div show.bind="!isLoading">Content is ready</div>
<div hide.bind="isHidden">Hidden when true</div>
<div show.bind="!isHidden">Hidden when true</div>
<!-- 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>
// 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>
<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>
<template switch.bind="orderStatus">
  <span case="received" fall-through="true">Order received</span>
  <span case="processing">Processing your order</span>
</template>
<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>
<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>
<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>
<!-- 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>
<!-- âś… 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>
<template switch.bind="status">
  <span case="received">Received</span>
  <span case="processing">Processing</span>
  <span default-case>Unknown</span> <!-- Last -->
</template>