diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/cover.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/cover.png new file mode 100644 index 0000000000..90401eacef Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-basic-theme-dashboard.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-basic-theme-dashboard.png new file mode 100644 index 0000000000..06416698a7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-basic-theme-dashboard.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-identity-users.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-identity-users.png new file mode 100644 index 0000000000..17ab8684ea Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-identity-users.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-leptonx-dashboard.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-leptonx-dashboard.png new file mode 100644 index 0000000000..586cfaaed7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-leptonx-dashboard.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-leptonx-lite-dashboard.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-leptonx-lite-dashboard.png new file mode 100644 index 0000000000..5e77d998a0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-leptonx-lite-dashboard.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-permission-management.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-permission-management.png new file mode 100644 index 0000000000..b1842a6727 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-permission-management.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-saas-tenants.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-saas-tenants.png new file mode 100644 index 0000000000..87bae5b787 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-saas-tenants.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-studio-blazor-ui-library-dropdown.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-studio-blazor-ui-library-dropdown.png new file mode 100644 index 0000000000..c03c045682 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-studio-blazor-ui-library-dropdown.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-studio-first-run.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-studio-first-run.png new file mode 100644 index 0000000000..02b0e8e264 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-studio-first-run.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-vs-blazorise-leptonx.png b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-vs-blazorise-leptonx.png new file mode 100644 index 0000000000..3864805c0d Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/mud-vs-blazorise-leptonx.png differ diff --git a/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/post.md b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/post.md new file mode 100644 index 0000000000..ca3098f8a1 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-09-mudblazor-in-abp-framework/post.md @@ -0,0 +1,213 @@ +# ABP 10.4.2 Expands Blazor UI Options with MudBlazor Support + +With ABP 10.4.2, new Blazor projects can now use **MudBlazor** (Material Design) as an alternative to the long-standing default, **Blazorise** (Bootstrap 5). Framework, themes (LeptonX / LeptonX Lite / Basic), modules, solution templates, ABP Studio, and ABP Suite all support both libraries side by side. The 10.4.2 packages are live on nuget.org. + +## Why add another Blazor UI library? + +Blazorise has been ABP's default Blazor UI library for years and **remains the default and is fully supported** — existing Blazorise projects can keep moving at their own pace, and upgrading to 10.4 does not change anything for them. + +We added MudBlazor because one Blazor UI choice cannot fit every team: + +- **Design language** — Bootstrap and Material Design serve different audiences, and forcing a single choice does not fit every team +- **Open-source preference** — MudBlazor is MIT-licensed, which works well for teams that want an open-source frontend component stack without extra component-library licensing or compliance overhead +- **Ecosystem fit** — Material Design third-party components (charts, rich text editors, data visualization, and so on) tend to integrate more naturally with a MudBlazor project + +For new projects you can start with MudBlazor right away. Existing Blazorise projects do not need to be rewritten just to switch UI libraries. + +### Who should consider MudBlazor? + +- Teams that want the frontend component stack **fully open source** with no licensing to manage (individual developers, open-source community projects, education / learning settings) +- Organizations with internal **third-party dependency or supply-chain compliance** requirements that prefer MIT-licensed components +- New Blazor projects that want to start with **Material Design** +- Teams already comfortable with the **MudBlazor ecosystem** (charts, rich text, rich UI components) + +## What the MudBlazor option covers + +### Framework core + +`Volo.Abp.MudBlazorUI` provides the MudBlazor implementation of ABP's UI service abstractions, so code written against `IUiMessageService` / `IUiNotificationService` / `IUiPageProgressService` runs unchanged in a MudBlazor project. Key building blocks: + +- `MudBlazorUiMessageService` — `Info` / `Success` / `Warn` / `Error` / `Confirm` rendered through `MudDialog` +- `MudBlazorUiNotificationService` — toast notifications via `MudSnackbar` +- `MudBlazorUiPageProgressService` — top progress bar via `MudProgressLinear` +- `AbpMudCrudPageBase<...>` — the MudBlazor counterpart to Blazorise's `AbpCrudPageBase` +- `AbpMudExtensibleDataGrid` — a `MudDataGrid` wrapper integrated with Object Extension and time-zone conversion +- `UiMessageAlert` / `UiNotificationAlert` / `PageAlert` — page-level alert and notification containers + +Theming is split across three hosts — Blazor Server, WebAssembly, and MauiBlazor — each shipped with matching bundling contributors and modules that wire MudBlazor's JS and CSS into the ABP bundle system. + +### Three themes + +- **LeptonX MudBlazor** +- **LeptonX Lite MudBlazor** +- **Basic Theme MudBlazor** + +Each theme's layout adopts MudBlazor components such as `MudAppBar`, `MudDrawer`, `MudNavLink`, and `MudMenu`, while keeping the theme's original color palette, dim / light / system modes, and RTL support. + +![LeptonX MudBlazor Dashboard](mud-leptonx-dashboard.png) +*LeptonX rendered with MudBlazor* + +![LeptonX Lite MudBlazor Dashboard](mud-leptonx-lite-dashboard.png) +*LeptonX Lite rendered with MudBlazor* + +![Basic Theme MudBlazor Dashboard](mud-basic-theme-dashboard.png) +*Basic Theme rendered with MudBlazor* + +The LeptonX themes reuse the same `lpx-*` CSS classes across both UI libraries, so the overall information architecture, page layout, and theme experience stay consistent with the Blazorise version. Individual controls follow each UI library's own conventions. + +![Blazorise vs MudBlazor on the same LeptonX theme](mud-vs-blazorise-leptonx.png) +*The same LeptonX theme — MudBlazor on the left, Blazorise on the right* + +### Module coverage + +Open-source modules in `abpframework/abp` that ship with a MudBlazor implementation: + +- **Account** +- **Identity** — Users / Roles / OUs / ClaimTypes +- **Permission Management** — parent/child permissions with `MudTreeView` and tri-state `MudCheckBox` +- **Setting Management** — grouped settings with `MudTabs` (including theme switching) +- **Tenant Management** +- **Feature Management** + +Additional MudBlazor implementations available on the Pro side, for example: + +- **Identity Pro** — extra management around Sessions, SecurityLogs, and more +- **OpenIddict Pro** — Application / Scope management +- **Saas** — Tenant / Edition management with a connection-string dialog +- **Audit Logging** — `MudDataGrid` with a detail `MudDialog` +- **Language Management** / **Text Template Management** +- **File Management** / **Chat** / **CMS Kit Pro** +- **AI Management** / **GDPR** / **Payment**, and more + +![Identity user management with MudDataGrid](mud-identity-users.png) +*Identity user management built on `AbpMudExtensibleDataGrid`* + +![Permission management modal](mud-permission-management.png) +*Permission Management uses `MudTreeView` and tri-state `MudCheckBox` for parent/child permissions* + +![Saas tenants list](mud-saas-tenants.png) +*Saas module: tenant list with a "New tenant" dialog that includes connection-string editing* + +### Component mapping at a glance + +If you already know Blazorise, here are the most common mappings: + +| Blazorise | MudBlazor | +|-----------|-----------| +| `TextEdit @bind-Text` | `MudTextField @bind-Value` | +| `Select / SelectItem` | `MudSelect / MudSelectItem` | +| `DataGrid` | `MudDataGrid` (wrapped by ABP as `AbpMudExtensibleDataGrid`) | +| `Modal Show()/Hide()` | `MudDialog ShowAsync()/CloseAsync()` | +| `Validations` | `MudForm` + built-in validation | +| `Row / Column ColumnSize.Is6` | `MudGrid / MudItem xs="12" sm="6"` | +| Bootstrap Icons `bi-*` | `Icons.Material.Filled.*` | + +A full mapping table with razor examples lives in the [ABP Blazor UI documentation](https://abp.io/docs/latest/framework/ui/blazor). + +### Supported Blazor project types + +ABP's MudBlazor support covers the Blazor project types you can create and run directly: + +- **Blazor Server** (`-u blazor-server`) +- **Blazor WebAssembly** (`-u blazor`) +- **Blazor WebApp** (`-u blazor-webapp`, including InteractiveAuto) + +### ABP Suite + +ABP Suite detects the solution's UI library and generates the matching CRUD page automatically: + +```csharp +public partial class Books : AbpMudCrudPageBase +{ + private MudDialog _createDialog; + private MudForm _createFormRef; +} +``` + +The razor templates also split by UI library — Blazorise uses `` + `` + ``, MudBlazor uses `` + `` + ``. + +## Choosing between Blazorise and MudBlazor + +Both UI libraries are production-ready and neither is strictly better. Common factors: + +- **Familiarity** — teams comfortable with Bootstrap tend to stay on Blazorise; teams comfortable with Material Design pick MudBlazor +- **Design system** — Bootstrap-style products lean toward Blazorise, Material Design products lean toward MudBlazor +- **Ecosystem** — existing Bootstrap component libraries or design assets fit Blazorise; Material Design third-party components fit MudBlazor more naturally +- **Existing projects** — keep maintaining live Blazorise projects as they are; if you want to try MudBlazor, start a new project with it +- **Licensing** — the two UI libraries have different license terms, so check each library's official license page before making a choice ([Blazorise](https://blazorise.com/license) / [MudBlazor](https://github.com/MudBlazor/MudBlazor/blob/dev/LICENSE)) + +Do not mix the two libraries within a single project — the choice is per solution, not per file. + +## Creating a MudBlazor project in ABP Studio + +### ABP Studio (recommended) + +Open ABP Studio → **New Solution** → pick a template → in the UI configuration step, select **Blazor UI library = MudBlazor**. Everything else works the same as a Blazorise project. After Build & Run you land on a MudBlazor-styled application. + +![ABP Studio New Solution wizard with MudBlazor selected](mud-studio-blazor-ui-library-dropdown.png) +*New Solution wizard: pick MudBlazor for the Blazor UI library* + +![First run after creation](mud-studio-first-run.png) +*Studio Build & Run brings up a MudBlazor + LeptonX dashboard in the embedded browser* + +### CLI + +```bash +# Blazorise (default; --blazor-ui-library can be omitted) +abp new MyApp -u blazor + +# MudBlazor +abp new MyApp -u blazor --blazor-ui-library mudblazor + +# Tiered + WebApp + LeptonX + MudBlazor +abp new MyApp -t app --tiered -u blazor-webapp --blazor-ui-library mudblazor --theme leptonx + +# Microservice + MudBlazor + Blazor Server +abp new MyApp -t microservice -u blazor-server --blazor-ui-library mudblazor + +# Reusable Module + MudBlazor +abp new My.Module -t module -u blazor --blazor-ui-library mudblazor +``` + +Run `abp new --help` for the full option list. + +Suite-generated MudBlazor CRUD pages are covered in the **ABP Suite** section above. + +--- + +## Try it out + +```bash +abp new MyMudApp -u blazor-server --blazor-ui-library mudblazor --theme leptonx +``` + +Documentation: + +- [Forms & Validation (MudBlazor)](https://abp.io/docs/latest/framework/ui/blazor/forms-validation?BlazorUI=MudBlazor) +- [LeptonX with MudBlazor](https://abp.io/docs/latest/ui-themes/lepton-x/blazor) +- [Basic Theme MudBlazor variant](https://abp.io/docs/latest/framework/ui/blazor/basic-theme) +- [Page Header (MudBlazor)](https://abp.io/docs/latest/framework/ui/blazor/page-header) + +## FAQ + +**I'm already using Blazorise — will upgrading to 10.4 / 10.4.2 break my project?** +No. Blazorise stays the default, and package paths, type names, and namespaces are fully compatible. Follow the standard ABP upgrade flow. + +**Can I use Blazorise and MudBlazor in the same project?** +We don't recommend it. The UI library is a project-level choice — themes, bundling, and module dependencies all switch with it. Mixing both within a single solution leads to bundle conflicts, duplicated layouts, and similar issues. + +**What about my custom razor pages?** +Your custom Razor pages are tied to the UI library they were built with, so switching libraries means rewriting those pages using the component mapping above. Template-generated pages and module-provided pages don't need to be touched. + +## Wrapping up + +MudBlazor is now a first-class Blazor UI library in ABP. With 10.4.2 released, every related package, theme, template, Studio integration, and Suite generator is in place — you can try it out with a single `abp new` command. + +If you hit a bug, have a suggestion, or want a particular module's MudBlazor UX prioritized, let us know via [GitHub Issues](https://github.com/abpframework/abp/issues) or [abp.io support](https://abp.io/support). + +## References + +- [MudBlazor official site](https://mudblazor.com) +- [ABP Blazor UI documentation](https://abp.io/docs/latest/framework/ui/blazor) +- [ABP LeptonX theme](https://abp.io/themes/leptonx) +- [ABP Studio download](https://abp.io/studio)