# Performance Optimization

Performance is more than speed. It is responsiveness, stability, and fluidity at every interaction. After building a solid foundation with htmx and Razor Pages, after layering in forms, tabs, modals, history management, and drag-and-drop interactivity, you need to look under the hood and refine how everything runs. This chapter focuses on smart, thoughtful enhancements that make your app feel fast without burning through server resources or exhausting browser patience.

You have seen how htmx handles interactions by communicating directly with the server using small, focused HTTP requests. But as your UI grows more dynamic and your users become more active, you will notice where optimizations matter most. Knowing when to prevent unnecessary requests, when to cache previously loaded content, and how to coordinate competing interactions can turn a sluggish interface into something satisfying to use.

This chapter explores patterns and techniques for improving performance from both client and server perspectives. You will learn how to reduce network chatter, streamline rendering, and prevent the classic pitfalls of excessive or redundant requests. You will also see how to synchronize competing requests so they do not corrupt your data or confuse your users.

Before moving into building a real-world dashboard in the next chapter, this chapter serves as your final checkpoint. It is where you tighten the bolts, polish the engine, and make sure the interactive experience you have built runs at its best.

When htmx makes it easy to fetch and swap content with just a few attributes, you will be tempted to use it everywhere. That temptation is part of its appeal. But unintentional overuse can silently degrade performance. One of the most common pitfalls in growing htmx applications is triggering more requests than necessary. Search boxes firing on every keystroke, buttons clicked repeatedly in quick succession, filters that race each other and arrive out of order: these inefficiencies add up fast, especially as your user base grows.

A good starting point for reducing server load is understanding where redundant or excessive requests happen. Dynamic search inputs are a frequent culprit. Developers often bind hx-get to keyup events without any delay, resulting in a flood of server requests as users type. This creates strain on your backend and jittery UX as responses race to update the DOM, sometimes arriving out of order.

Consider a search form where results appear as the user types. A naive implementation might look like this:

<input type="text"
       name="query"
       hx-get="/Search?handler=Results"
       hx-target="#results"
       hx-trigger="keyup" />
<div id="results"></div>

Every single keystroke fires a request. If your user types quickly, that could mean 10 or more server calls in just a few seconds. The solution is throttling. Adding delay:500ms to hx-trigger introduces a half-second pause after typing stops before firing the request. Combined with changed, which ensures it only triggers if the value has actually changed, this drastically cuts the number of requests:

<input type="text"
       name="query"
       hx-get="/Search?handler=Results"
       hx-target="#results"
       hx-trigger="keyup changed delay:500ms" />

This simple change alone can reduce server requests by 80 to 90 percent in many cases. Throttling and debouncing are foundational patterns for interactive elements that respond to rapid user input. While htmx handles some of this internally, explicitly controlling trigger behavior with delay settings gives you more predictable and scalable performance.

On the server side, your Razor Page handler stays lean:

public class SearchModel : PageModel
{
    public IActionResult OnGetResults(string query)
    {
        var results = GetResults(query ?? string.Empty);
        return Partial("_SearchResults", results);
    }

    private List<string> GetResults(string query)
    {
        var data = new List<string> { "apple", "banana", "apricot", "blueberry" };
        return data.Where(x => x.Contains(query, StringComparison.OrdinalIgnoreCase)).ToList();
    }
}

The _SearchResults.cshtml partial returns a simple list of results, allowing htmx to update the UI efficiently without loading or redrawing anything unrelated.

By optimizing when and how requests are sent, you help your server operate more efficiently and deliver a smoother experience to users. As your application scales, these adjustments make the difference between an app that groans under traffic and one that handles it with grace.

Debouncing helps reduce request volume, but it does not solve every problem. What happens when a user changes a dropdown while a previous request is still in flight? What if they click a button twice before the first response arrives? These race conditions can corrupt your UI by displaying stale data or applying updates in the wrong order.

The hx-sync attribute coordinates requests from related elements, ensuring they do not compete in destructive ways. It specifies a synchronization scope and a strategy for handling conflicts.

For search boxes and filters, the abort strategy cancels any in-flight request when a new one starts:

<input type="text"
       name="query"
       hx-get="/Search?handler=Results"
       hx-target="#results"
       hx-trigger="keyup changed delay:300ms"
       hx-sync="this:abort" />

<div id="results"></div>

With hx-sync="this:abort", if the user types "cat" while a request for "ca" is still pending, the "ca" request gets cancelled. The results will always reflect the most recent input, never an outdated intermediate state.

For operations that should not be interrupted, the drop strategy ignores new requests while one is running:

<button hx-post="/Reports?handler=Generate"
        hx-target="#report-output"
        hx-sync="this:drop"
        hx-disabled-elt="this"
        hx-indicator="#generating">
    Generate Report
    <span id="generating" class="htmx-indicator">Working...</span>
</button>

<div id="report-output"></div>

If the user clicks while a report is generating, the second click is ignored entirely. Combined with hx-disabled-elt to visually disable the button, this creates a foolproof interaction that cannot produce duplicate reports.

When several elements can trigger requests that update the same target, synchronize them against a common ancestor:

<div id="product-filters">
    <select name="category"
            hx-get="/Products?handler=Filter"
            hx-target="#product-list"
            hx-trigger="change"
            hx-sync="#product-filters:abort"
            hx-include="#product-filters">
        <option value="">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="clothing">Clothing</option>
    </select>

    <select name="sort"
            hx-get="/Products?handler=Filter"
            hx-target="#product-list"
            hx-trigger="change"
            hx-sync="#product-filters:abort"
            hx-include="#product-filters">
        <option value="name">Sort by Name</option>
        <option value="price">Sort by Price</option>
    </select>

    <input type="text"
           name="search"
           placeholder="Search..."
           hx-get="/Products?handler=Filter"
           hx-target="#product-list"
           hx-trigger="keyup changed delay:300ms"
           hx-sync="#product-filters:abort"
           hx-include="#product-filters" />
</div>

<div id="product-list"></div>

All three controls synchronize against #product-filters. If a user changes the category while a search request is running, the search request aborts and the category request proceeds. The product list always reflects the most recent user action.

The server handler receives all filter parameters:

public class ProductsModel : PageModel
{
    private readonly IProductRepository _products;

    public ProductsModel(IProductRepository products)
    {
        _products = products;
    }

    public IActionResult OnGetFilter(string category, string sort, string search)
    {
        var query = _products.GetAll();

        if (!string.IsNullOrEmpty(category))
        {
            query = query.Where(p => p.Category == category);
        }

        if (!string.IsNullOrEmpty(search))
        {
            query = query.Where(p => 
                p.Name.Contains(search, StringComparison.OrdinalIgnoreCase));
        }

        query = sort switch
        {
            "price" => query.OrderBy(p => p.Price),
            _ => query.OrderBy(p => p.Name)
        };

        return Partial("_ProductList", query.ToList());
    }
}

Lazy loading defers fetching content until it is actually needed. Instead of overwhelming the browser and backend by loading everything up front, you spread the work across the user's session. This approach improves perceived performance and reduces bandwidth usage, which matters most when dealing with large datasets, media-heavy pages, or sections hidden until scrolled into view.

htmx makes lazy loading almost effortless using hx-get combined with hx-trigger="revealed". The revealed trigger fires when an element becomes visible in the viewport. You can delay loading sections of your page until the user scrolls down to them, reducing initial page load time significantly.

Suppose you have a report with several data tables, and only the first one is visible when the page loads. Rather than load all of them at once, lazy load the others as the user scrolls:

<div hx-get="/Reports?handler=SalesData"
     hx-trigger="revealed"
     hx-swap="outerHTML"
     class="lazy-section">
    <p>Loading sales data...</p>
</div>

On the server side:

public class ReportsModel : PageModel
{
    public IActionResult OnGetSalesData()
    {
        var data = GetSalesData();
        return Partial("_SalesTable", data);
    }

    private List<Sale> GetSalesData()
    {
        return Enumerable.Range(1, 1000)
            .Select(i => new Sale 
            { 
                Id = i, 
                Product = $"Item {i}", 
                Amount = i * 10m 
            })
            .ToList();
    }
}

public class Sale
{
    public int Id { get; set; }
    public string Product { get; set; }
    public decimal Amount { get; set; }
}

The _SalesTable.cshtml partial renders the table. With this setup, the placeholder div swaps out with actual content once it becomes visible in the browser. The interaction feels smooth without blocking initial page load.

You can extend lazy loading to create infinite scrolling. Each batch of content includes a loader for the next batch at the bottom:

<!-- _MessageBatch.cshtml -->
@model MessageBatchViewModel

@foreach (var message in Model.Messages)
{
    <div class="message">
        <strong>@message.Author</strong>
        <p>@message.Content</p>
        <small>@message.Timestamp.ToString("g")</small>
    </div>
}

@if (Model.HasMore)
{
    <div hx-get="/Messages?handler=Batch&amp;offset=@Model.NextOffset"
         hx-trigger="revealed"
         hx-swap="outerHTML"
         class="loading-more">
        <p>Loading more messages...</p>
    </div>
}

The server sends both content and the next loader. Users see endless scrolling without overwhelming the page:

public IActionResult OnGetBatch(int offset = 0)
{
    const int batchSize = 20;
    var messages = _messageService.GetMessages(offset, batchSize + 1);
    
    var viewModel = new MessageBatchViewModel
    {
        Messages = messages.Take(batchSize).ToList(),
        HasMore = messages.Count > batchSize,
        NextOffset = offset + batchSize
    };
    
    return Partial("_MessageBatch", viewModel);
}

Taking one extra record lets you determine if more content exists without a separate count query.

For media-heavy pages, wrap images in containers that load actual markup only when visible:

<div hx-get="/Gallery?handler=Image&amp;id=123"
     hx-trigger="revealed"
     hx-swap="outerHTML"
     class="image-placeholder"
     style="aspect-ratio: 16/9; background: #eee;">
</div>

The server returns the actual image tag:

public IActionResult OnGetImage(int id)
{
    var image = _gallery.GetImage(id);
    return Content($"<img src=\"{image.Url}\" alt=\"{image.Title}\" loading=\"lazy\" />", "text/html");
}

This reduces the number of active image requests on initial load, giving users a faster and more responsive browsing experience.

When users click the back button, they expect instant results. Without caching, htmx would need to re-fetch content from the server. History caching stores previously loaded content and restores it immediately during navigation.

When you use hx-push-url="true", htmx automatically caches the current page state before navigation. The hx-history-elt attribute specifies which element should be snapshotted. Place it on the container whose content represents your page's main state:

<nav>
    <button hx-get="/Dashboard?handler=Overview"
            hx-target="#main-content"
            hx-push-url="/dashboard/overview">
        Overview
    </button>
    <button hx-get="/Dashboard?handler=Analytics"
            hx-target="#main-content"
            hx-push-url="/dashboard/analytics">
        Analytics
    </button>
    <button hx-get="/Dashboard?handler=Settings"
            hx-target="#main-content"
            hx-push-url="/dashboard/settings">
        Settings
    </button>
</nav>

<main id="main-content" hx-history-elt>
    <!-- Dashboard content loads here -->
    <!-- This element's innerHTML gets cached on navigation -->
</main>

The hx-history-elt attribute on #main-content tells htmx to snapshot that element's innerHTML when the URL changes. When users navigate back, htmx restores the cached content instantly without a server request.

Some content should not be cached. Sensitive information, rapidly changing data, or personalized content might become stale or inappropriate to restore. Use hx-history="false" to exclude specific requests from caching:

<button hx-get="/Account?handler=SecuritySettings"
        hx-target="#main-content"
        hx-push-url="/account/security"
        hx-history="false">
    Security Settings
</button>

This still updates the URL but does not cache the response. Navigating back will trigger a fresh server request.

htmx stores history in localStorage with a default limit of 10 pages. Adjust this based on your application's needs:

htmx.config.historyCacheSize = 20;

Set it to zero to disable history caching entirely while keeping URL updates functional.

Sometimes a single user action needs to update multiple unrelated parts of the page. A form submission might need to refresh a data table, update a notification count, and show a status message. Making three separate requests wastes bandwidth and creates timing issues.

Out-of-band (OOB) updates let you include multiple fragments in a single response. htmx swaps the primary content into the target, then processes any elements marked with hx-swap-oob="true" and swaps them into matching elements elsewhere on the page.

Suppose submitting a support ticket should update the ticket list, notification badge, and show a confirmation message:

<form hx-post="/Support?handler=CreateTicket"
      hx-target="#ticket-list"
      hx-disabled-elt="find button[type='submit']">
    <textarea name="Description" required></textarea>
    <button type="submit">Submit Ticket</button>
</form>

<div id="ticket-list">
    <!-- Ticket list content -->
</div>

<header>
    <span id="notification-badge">5</span> notifications
</header>

<div id="status-message"></div>

Your server response includes the primary content plus OOB fragments:

public IActionResult OnPostCreateTicket([FromForm] string description)
{
    var ticket = _ticketService.Create(description);
    var tickets = _ticketService.GetAll();
    var unreadCount = _notificationService.GetUnreadCount();
    
    var html = new StringBuilder();
    
    // Primary response for #ticket-list
    html.Append(RenderPartial("_TicketList", tickets));
    
    // OOB update for notification badge
    html.Append($"<span id=\"notification-badge\" hx-swap-oob=\"true\">{unreadCount}</span>");
    
    // OOB update for status message
    html.Append("<div id=\"status-message\" hx-swap-oob=\"true\" class=\"success\">Ticket created successfully!</div>");
    
    return Content(html.ToString(), "text/html");
}

Or using a partial view that includes OOB elements:

<!-- _CreateTicketResponse.cshtml -->
@model CreateTicketResponseViewModel

<!-- Primary content -->
<partial name="_TicketList" model="Model.Tickets" />

<!-- OOB updates -->
<span id="notification-badge" hx-swap-oob="true">@Model.UnreadCount</span>

<div id="status-message" hx-swap-oob="true" class="success">
    Ticket created successfully!
</div>

htmx processes the response as follows:

1. Swaps the primary content (everything before the first OOB element) into #ticket-list
2. Finds #notification-badge in the current page and replaces it with the OOB version
3. Finds #status-message in the current page and replaces it with the OOB version

This pattern keeps your interactions efficient while handling complex UI updates in a single round trip.

Client-side optimizations only go so far. Your server needs to respond quickly with minimal payloads for htmx to feel fast.

htmx endpoints should return only the HTML needed for the swap. Avoid returning full page layouts:

// Good: Returns only the fragment
public IActionResult OnGetResults(string query)
{
    var results = _searchService.Search(query);
    return Partial("_SearchResults", results);
}

// Avoid: Returns full page
public IActionResult OnGetResults(string query)
{
    var results = _searchService.Search(query);
    ViewData["Results"] = results;
    return Page(); // Returns entire page layout
}

ASP.NET Core can compress responses, reducing transfer size for HTML fragments:

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    options.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(
        new[] { "text/html" });
});

// In the pipeline
app.UseResponseCompression();

For content that does not change frequently, cache the rendered output:

public class ReportsModel : PageModel
{
    private readonly IMemoryCache _cache;
    private readonly IReportService _reports;

    public ReportsModel(IMemoryCache cache, IReportService reports)
    {
        _cache = cache;
        _reports = reports;
    }

    public IActionResult OnGetSummary()
    {
        var cacheKey = "report-summary";
        
        if (!_cache.TryGetValue(cacheKey, out string cachedHtml))
        {
            var data = _reports.GetSummary();
            cachedHtml = RenderPartialToString("_ReportSummary", data);
            
            _cache.Set(cacheKey, cachedHtml, TimeSpan.FromMinutes(5));
        }
        
        return Content(cachedHtml, "text/html");
    }
}

Include server timing information in responses to help identify slow endpoints:

public IActionResult OnGetData()
{
    var stopwatch = Stopwatch.StartNew();
    
    var data = _dataService.GetData();
    
    stopwatch.Stop();
    Response.Headers.Add("Server-Timing", $"db;dur={stopwatch.ElapsedMilliseconds}");
    
    return Partial("_DataTable", data);
}

Browser developer tools display these timings in the Network tab, making performance issues visible during development.

When requests behave unexpectedly or performance degrades, htmx provides tools to understand what is happening.

The simplest debugging approach is enabling htmx logging:

htmx.logAll();

This outputs every htmx event to the console. For targeted debugging, listen for specific events:

document.body.addEventListener('htmx:beforeRequest', function(event) {
    console.log('Starting request:', event.detail.pathInfo.requestPath);
    console.time('htmx-request');
});

document.body.addEventListener('htmx:afterRequest', function(event) {
    console.timeEnd('htmx-request');
    console.log('Status:', event.detail.xhr.status);
});

document.body.addEventListener('htmx:sendError', function(event) {
    console.error('Request failed:', event.detail.error);
});

Your browser's Network tab reveals:

• Which requests htmx is firing
• Request frequency (are triggers too aggressive?)
• Response sizes (are you returning too much HTML?)
• Timing breakdowns (where is time being spent?)

Filter by XHR/Fetch to see only AJAX requests and hide static assets.

Problem: Search fires too many requests. Solution: Add delay:300ms to debounce and hx-sync="this:abort" to cancel stale requests.

Problem: Page feels slow despite fast server responses. Solution: Check if you are returning too much HTML. Use browser paint profiling to identify rendering bottlenecks.

Problem: Back button triggers server requests instead of using cache. Solution: Verify hx-push-url is set and hx-history-elt is on the correct container element.

Problem: Multiple clicks create duplicate database entries. Solution: Add hx-disabled-elt to disable buttons during requests and hx-sync="this:drop" to ignore repeated clicks.

Problem: Filters update with stale data after rapid changes. Solution: Synchronize all filter elements with hx-sync against a common ancestor using the abort strategy.

Performance optimization with htmx combines several complementary techniques:

• Debouncing reduces request volume by waiting for user input to settle
• hx-sync prevents race conditions by coordinating competing requests
• Lazy loading defers content fetching until elements become visible
• History caching restores previously loaded content instantly during navigation
• Out-of-band updates handle complex multi-element updates in single responses
• Server optimizations ensure fast responses with minimal payloads

These patterns work together. A well-optimized htmx application debounces rapid input, synchronizes related controls, lazy loads heavy content, caches navigation states, and returns minimal server responses. The result is an interface that feels immediate and reliable, even as complexity grows.

In the next chapter, you will build a dynamic, data-rich dashboard using htmx and Razor Pages. You will apply these performance techniques across interactive charts, live updates, and admin panels to see how clean and responsive your applications can be when performance is part of the plan from the start.