ASP.NET Core Integration Guide

This guide explains how to integrate NextUI with ASP.NET Core applications (Blazor Server, Blazor United/Interactive Server).

Overview

When using NextUI with ASP.NET Core, you can enable:

  1. Cookie-based Settings Persistence - Theme, locale, and other user preferences are stored in cookies
  2. SSR Theme Injection - Prevents theme flicker by injecting theme attributes server-side
  3. ASP.NET Core Localization Integration - Works with ASP.NET Core's RequestLocalization middleware

Setup

1. Register Services

// Program.cs
using NextUI.Blazor.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddNextDesignSystemWithAspNetCore(options =>
{
    options.SupportedCultures = ["en-US", "zh-CN", "ja-JP"];
    options.DefaultCulture = "en-US";
});

var app = builder.Build();

app.UseNextUIRequestLocalization();
app.Run();

2. Include Required Scripts

In your App.razor or _Host.cshtml:

<head>
    <link rel="stylesheet" href="_content/NextUI.Blazor/Styles/sx-tokens.css" />
</head>
<body>
    <!-- Your app content -->

    <!-- REQUIRED: before Blazor script -->
    <script src="_content/NextUI.Blazor/js/nextui-interop.js"></script>
    <script src="_framework/blazor.server.js"></script>
</body>

3. SSR Theme Injection (Optional)

To prevent theme flicker during SSR:

<html lang="en" nextui-theme>

Configuration Options

builder.Services.AddNextDesignSystemWithAspNetCore(options =>
{
    // Cookie names
    options.ThemeCookieName = "NextUI.Theme";
    options.LocaleCookieName = ".AspNetCore.Culture";

    // Cookie settings
    options.CookieExpiration = TimeSpan.FromDays(365);
    options.SameSiteMode = SameSiteMode.Lax;
    options.SecureCookies = true;

    // Supported cultures
    options.SupportedCultures = ["en-US", "zh-CN"];
    options.DefaultCulture = "en-US";

    // Theme defaults
    options.DefaultThemeMode = "System";
    options.DefaultPrimaryColor = "#3B82F6";

    // Language change behavior
    options.LocaleChangeMode = LocaleChangeMode.Reload; // Default: reload page
});

Language Change Behavior

When the user changes language via SxAppGlobalMenu:

  1. Culture cookie is set
  2. Page is reloaded (default behavior)
  3. ASP.NET Core RequestLocalizationMiddleware reads the cookie and sets the culture
  4. All content renders in the new language

To disable automatic page reload:

options.LocaleChangeMode = LocaleChangeMode.None;

How It Works

  1. Reading: During SSR, CookieUserPreferences reads settings from HTTP cookies
  2. Writing: Settings changes are written to cookies via JavaScript

The locale cookie follows ASP.NET Core's format:

c=en-US|uic=en-US

Comparison

Feature AddNextDesignSystem() AddNextDesignSystemWithAspNetCore()
Storage localStorage HTTP Cookies
SSR Support No Yes
Theme Flicker May occur Prevented
Platform WebAssembly, MAUI Blazor Server

Troubleshooting

Settings Not Persisted

Add the interop script:

<script src="_content/NextUI.Blazor/js/nextui-interop.js"></script>

Theme Flicker on Initial Load

Add the nextui-theme attribute:

<html lang="en" nextui-theme>

Console Error: "NextUI.setCookie is not defined"

The nextui-interop.js script is not loaded. Add the script reference.