MudShell 0.7.3

MudShell

A Razor Class Library of opinionated Blazor components built on top of MudBlazor 9, designed for dark-mode AI-shell style applications.

Features

• 🎨 Pre-configured dark/light MudTheme — just call CreateDarkTheme()
• 🗂 MdsAppShell — full-page shell with collapsible sidebar, background image/palette modes
• 🌲 Unified hierarchical navigation with MbxNavTree (MdsSidebarNav, MdsContextNavPanel, MbxMobileDrilldownNav)
• 🖥️ Desktop-first shell with collapsible sidebar navigation
• 💬 MdsChatBar — glassmorphism input bar
• 🤖 Chat set — MdsChatComposer, MdsChatTranscript, MdsChatMessage, MdsChatStream, MdsChatLanding
• 🃏 MdsDocumentCard, MdsFilterTabBar, MdsPageHeader
• 🧩 Main-content primitives (MdsMainToolbar, MdsMainSection, MdsMainPart, MdsMainEmptyState)
• 📐 Fill-layout blocks — MdsFillLayout, MdsFillRegion, MdsSplitPane, MdsTabbedFill (full-screen pages, only leaf regions scroll)
• 📊 Data blocks — MdsStatTile/MdsStatStrip, MdsDistributionBar, MdsSparkline, MdsRunStrip; nav badges on MbxNavNode.Badge
• All components use scoped CSS — zero global style pollution

Quick start

1. Add the project reference

<ItemGroup>
  <ProjectReference Include="..\MudShell\MudShell.csproj" />
</ItemGroup>

2. Register services

// Program.cs
builder.Services.AddMudShell();

AddMudShell() also registers the Radzen DialogService used by MdsScheduler. No other Radzen service is registered.

3. Add global imports

@* _Imports.razor *@
@using MudShell
@using MudShell.Components.AppShell
@using MudShell.Components.Sidebar
@using MudShell.Components.BottomNav
@using MudShell.Components.ChatBar
@using MudShell.Components.DocumentCard
@using MudShell.Components.FilterTabBar
@using MudShell.Components.MainContent
@using MudShell.Components.PageHeader

4. Add MudBlazor providers to your root component

MdsAppShell is a pure layout shell — it does not register MudBlazor providers internally. You must declare them once in your app's root component (e.g. Routes.razor) to avoid a duplicate section-ID crash at runtime:

@* Routes.razor *@
<MudThemeProvider Theme="@myTheme" />
<MudPopoverProvider />
<MudSnackbarProvider />
<MudDialogProvider />

<Router AppAssembly="typeof(App).Assembly">
    ...
</Router>

5. Use MdsAppShell in your layout

@* MainLayout.razor *@
@inherits LayoutComponentBase

<MdsAppShell BackgroundMode="MdsAppShell.MbxBackgroundMode.Palette">
  <SidebarContent>
    
  </SidebarContent>
  <ContextPanelContent>
    
  </ContextPanelContent>
  <ChildContent>
    @Body
  </ChildContent>
</MdsAppShell>

Optional: the scheduler (Radzen)

MdsScheduler<TItem> renders the free and open-source Radzen Blazor scheduler (MIT). Radzen is a dependency of MudShell and stays internal: the component loads its own stylesheet and script, so no extra host setup is needed. See the scheduler docs for usage.

Hierarchical single-source navigation

<MdsAppShell @ref="_shell"
  ContextPanelExpanded="@_contextExpanded"
  ContextPanelExpandedChanged="@(v => _contextExpanded = v)"
  ContextPanelWidth="320"
  ContextPanelCollapsedWidth="72">
  <SidebarContent>
    <MdsSidebarNav Tree="@AppNav.Tree" />
  </SidebarContent>
  <ContextPanelContent>
    <MdsContextNavPanel Tree="@AppNav.Tree" IsExpanded="@_contextExpanded" />
  </ContextPanelContent>
  <ChildContent>@Body</ChildContent>
</MdsAppShell>

You can collapse/expand the level-2 panel at runtime with:

_shell.ToggleContextPanel();

Recommended page layout pattern (sample app)

The sample is an English-language UI showcase, with technical material kept separate:

Each component family has a live demo and collapsible usage details. The navigation demo at /components/navigation includes two independent contextual submenus and a sidebar specimen with pinned items, removal and drag-and-drop. Event logs are collapsed by default. /components/navigation/mobile demonstrates both mobile navs.

Appearance, at the bottom of the sidebar even when collapsed, selects an existing theme preset, light/dark mode, background and density. These settings are shared across in-app navigation; the showcase does not expose custom color editing. Historical demo URLs remain available as aliases. Background and render-mode variants are compatibility scenarios, not additional catalogue entries.

The sample has no stylesheets or inline CSS. Pages compose MudShell components and MudBlazor controls using their public parameters and built-in utilities. Layout fixes belong in MudShell, not in sample-specific overrides.

MdsMainSection and MdsMainPart use neutral theme text for titles and supporting copy by default. TitleColor remains available for intentional accent headings; Color.Secondary is a brand accent, not muted text.

Run the sample with dotnet run --project samples\MyApplication and run UI tests against the running instance using PLAYWRIGHT_TEST_BASE_URL (default http://localhost:5265):

$env:PLAYWRIGHT_TEST_BASE_URL = "http://localhost:5265"
dotnet test tests\MudShell.UITests\MudShell.UITests.csproj

For pages with actions and filters, use this structure:

1. Top action bar with MdsMainToolbar (primary actions on the left, UI config on the right with MudSpacer).
2. Filter row below with a horizontal MudStack of MudChip filters.
3. Keep the filter row directly on the page background (no bordered MudPaper wrapper).

This pattern is used in the sample pages (for example MeteoPage and EuropeCitiesDashboard) for consistent UX.

For a full page blueprint and MudBlazor migration guidance, see the dedicated docs below.

Documentation

• Getting started
• MudBlazor integration
• Page blueprint
• Model
• Theming
• Responsive
• Architecture
• Components: AppShell · Sidebar · BottomNav · ChatBar · Chat · DocumentCard · FilterTabBar · PageHeader · Scheduler