A powerful React Router-like routing library for Blazor applications. Blazouter brings advanced routing features to Blazor including nested routes, route guards, lazy loading, smooth transitions, and programmatic navigation. This is the core library that works with all Blazor hosting models (Web, Server, WebAssembly and Hybrid/MAUI).
Get Started
$ dotnet add package BlazouterReadme
Blazouter - Core Library
A powerful React Router-like routing library for Blazor applications. This is the core library that provides the foundational routing capabilities for all Blazor hosting models.
Features
- ✅ Type-safe - Full IntelliSense support
- ✅ True nested routing - Full hierarchical route structures
- ✅ Beautiful transitions - Smooth animations between routes
- ✅ Programmatic navigation - Navigate imperatively with ease
- ✅ Lazy loading - Load components on-demand for better performance
- ✅ Built-in route guards - Protect routes with authentication/authorization
- ✅ Dynamic route parameters - Easy access to route and query parameters
- ✅ Flexible layout system - Default and per-route layouts with @Body support
- ✅ Query string utilities - Type-safe query string builder and typed parameter parsing
- ✅ TypeScript integration - Optional JavaScript interop for browser History and Document APIs
Installation
dotnet add package Blazouter
For hosting-specific implementations, also install:
- Blazor Server:
Blazouter.Server - Blazor Hybrid/MAUI:
Blazouter.Hybrid - Blazor WebAssembly:
Blazouter.WebAssembly
Quick Start
Blazor WebAssembly
// Program.cs
using Blazouter.Extensions;
builder.Services.AddBlazouter();
<!-- App.razor -->
@using Blazouter.Models
@using Blazouter.Components
<Router Routes="@_routes" DefaultLayout="typeof(MainLayout)">
<NotFound>
<h1>404 - Page Not Found</h1>
</NotFound>
</Router>
@code {
private List<RouteConfig> _routes = new()
{
new RouteConfig
{
Path = "/",
Component = typeof(Home),
Transition = RouteTransition.Fade
}
};
}
Blazor Server
// Program.cs
using Blazouter.Extensions;
using Blazouter.Server.Extensions;
builder.Services.AddBlazouter();
app.MapRazorComponents<App>()
.AddBlazouterSupport()
.AddInteractiveServerRenderMode();
Blazor Hybrid (MAUI)
// MauiProgram.cs
using Blazouter.Hybrid.Extensions;
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder.UseMauiApp<App>();
builder.Services.AddMauiBlazorWebView();
// Add Blazouter support
builder.AddBlazouterSupport();
return builder.Build();
}
}
<!-- Main.razor or your root component -->
@using Blazouter.Models
@using Blazouter.Components
<Router Routes="@_routes">
<NotFound>
<h1>404 - Page Not Found</h1>
</NotFound>
</Router>
@code {
private List<RouteConfig> _routes = new()
{
new RouteConfig
{
Path = "/",
Component = typeof(Home),
Transition = RouteTransition.Fade
}
};
}
Key Components
Router Component
The main router component that handles route matching and rendering.
RouterOutlet Component
Used in parent components to render child routes in nested routing scenarios.
RouterLink Component
Navigation links with automatic active state detection.
<RouterLink Href="/" Exact="true" ActiveClass="active">Home</RouterLink>
<RouterLink Href="/about" ActiveClass="active">About</RouterLink>
Layouts
Set a default layout for all routes and override per route:
<Router Routes="@_routes" DefaultLayout="typeof(MainLayout)">
<NotFound><h1>404</h1></NotFound>
</Router>
@code {
private List<RouteConfig> _routes = new()
{
// Uses DefaultLayout (MainLayout)
new RouteConfig { Path = "/", Component = typeof(Home) },
// Override with different layout
new RouteConfig
{
Path = "/admin",
Component = typeof(Admin),
Layout = typeof(AdminLayout)
},
// No layout for this route
new RouteConfig
{
Path = "/print",
Component = typeof(Print),
Layout = null
}
};
}
Route Configuration
new RouteConfig
{
Path = "/users",
Component = typeof(UserLayout),
Title = "Users",
Layout = typeof(MainLayout), // Optional: override default layout
Transition = RouteTransition.Slide,
Guards = new List<Type> { typeof(AuthGuard) },
Children = new List<RouteConfig>
{
new RouteConfig
{
Path = ":id",
Component = typeof(UserDetail)
}
}
}
Route Guards
Create custom guards by implementing IRouteGuard:
using Blazouter.Models;
using Blazouter.Interfaces;
public class AuthGuard : IRouteGuard
{
public async Task<bool> CanActivateAsync(RouteMatch match)
{
return await IsAuthenticated();
}
public Task<string?> GetRedirectPathAsync(RouteMatch match)
{
return Task.FromResult<string?>("/login");
}
}
Lazy Loading
new RouteConfig
{
Path = "/reports",
ComponentLoader = async () =>
{
await Task.Delay(100); // Simulated delay
return typeof(ReportsPage);
}
}
Programmatic Navigation
@inject RouterNavigationService NavService
private void NavigateToUser()
{
NavService.NavigateTo("/users/123");
}
Route Parameters
@inject RouterStateService RouterState
protected override void OnInitialized()
{
var userId = RouterState.GetParam("id");
}
Query String Utilities
Type-safe query string manipulation with fluent API:
@using Blazouter.Utilities
@using Blazouter.Extensions
@inject RouterStateService RouterState
@inject RouterNavigationService NavService
// Typed query parameter parsing
protected override void OnInitialized()
{
int page = RouterState.GetQueryInt("page", 1);
bool active = RouterState.GetQueryBool("active", false);
DateTime? date = RouterState.GetQueryDateTimeOrNull("date");
}
// Fluent query string building
private void SearchWithFilters()
{
NavService.NavigateToWithQuery("/search", q => q
.Add("term", "blazor")
.Add("active", true)
.Add("page", 2));
}
// Update query parameters
private void NextPage()
{
NavService.NavigateToWithUpdatedQuery(RouterState, null, q => q
.Set("page", currentPage + 1));
}
Supported types: string, int, long, decimal, double, bool, DateTime, Guid, enum, and nullable variants (15 type-safe methods each for Add() and Set()).
TypeScript Integration (Optional)
Enhanced browser integration with type-safe JavaScript interop using 5 specialized services:
// Enable JavaScript interop (optional)
builder.Services.AddBlazouterInterop();
Add to your index.html:
<script type="module" src="_content/Blazouter/js/index.js"></script>
Available Services:
- ClipboardInterop: Clipboard operations (copy, read, permissions)
- StorageInterop: localStorage & sessionStorage with JSON serialization
- NavigationInterop: Browser History API (back/forward, URL info, hash, query params)
- ViewportInterop: Viewport/device info (dimensions, device type, orientation, fullscreen)
- DocumentInterop: Document manipulation (title, meta tags, scrolling, focus, CSS classes)
@using Blazouter.Interops
@inject StorageInterop Storage
@inject DocumentInterop Document
@inject ViewportInterop Viewport
@inject ClipboardInterop Clipboard
@inject NavigationInterop Navigation
// Navigation
await Navigation.GoBackAsync();
string url = await Navigation.GetCurrentUrlAsync();
// Document
await Document.SetTitleAsync("Home - My App");
await Document.ScrollToTopAsync();
// Storage
await Storage.SetLocalStorageAsync("key", myObject);
var data = await Storage.GetLocalStorageAsync<MyType>("key");
// Viewport
string device = await Viewport.GetDeviceTypeAsync();
bool isMobile = await Viewport.IsMobileAsync();
// Clipboard
await Clipboard.CopyTextAsync("text");
Transitions
Built-in transitions: None, Pop, Blur, Fade, Flip, Lift, Scale, Slide, Swipe, Reveal, Rotate, Curtain, SlideUp, SlideFade, Spotlight
new RouteConfig
{
Path = "/",
Component = typeof(Home),
Transition = RouteTransition.Fade
}
Multi-Platform Support
- Blazor Server
- Blazor WebAssembly
- Blazor Hybrid (MAUI)
- .NET 6.0, 7.0, 8.0, 9.0, 10.0
Documentation
License
MIT License - see LICENSE for details.
Support
Made with ❤️ for the Blazor community