FAQ & Troubleshooting

Setup

Which .NET version does Marai.UI require?

Marai.UI requires .NET 10 or later. Verify your project file targets the correct framework:

<TargetFramework>net10.0</TargetFramework>

Do I need to call AddMaraiUI()?

Yes. Add the following to Program.cs before building the app:

using Marai.UI.DependencyInjection;

builder.Services.AddMaraiUI();

Without this call, services like ToastService will not resolve and components that depend on them will throw a runtime exception.

Components render but look completely unstyled — what's wrong?

The most common cause is a missing <MStyleInjector />. This component writes the CSS custom properties (--ring, --ring-offset, --muted) that Marai.UI components rely on for focus rings and neutral backgrounds.

Place it inside your root App.razor or root layout — once, anywhere in the component tree:

<MStyleInjector />

My Tailwind classes don't appear — styles are missing at runtime.

Tailwind only includes classes it finds as literal text at build time. Check the following:

• Your Styles/app.css input file includes @source directives that point to your .razor, .cshtml, and .cs files:
  css Copy

  @import "tailwindcss";
  @source "../**/*.razor";
  @source "../**/*.cshtml";
  @source "../**/*.cs";
  @source "../**/*.css";
  @source not "../bin/**";
  @source not "../obj/**";
  @source not "../node_modules/**";

• The build:css npm script ran during your last build.
• Your App.razor references tailwindcssv4.min.css from wwwroot.
• Class strings are literal — not assembled dynamically at runtime (see Best Practices).

The Blazor boilerplate Bootstrap styles conflict with my components.

The default Blazor project template includes Bootstrap via app.css or bootstrap.min.css. Bootstrap's global resets can conflict with Tailwind's base styles and Marai.UI components. The recommended fix is to remove or scope the Bootstrap reference and rely on Tailwind for all styling.

If you must keep Bootstrap, add Tailwind's @layer base resets before the Bootstrap import so Tailwind's normalizations take precedence where needed.

Components

MSwitch renders but the track doesn't appear.

MSwitch renders a track <span> only when TrackClass is supplied. If you omit TrackClass, no span is rendered. Pass at least a minimal set of utilities to show the track:

"<MSwitch InputClass=\"peer sr-only\" TrackClass=\"relative block w-11 h-6 rounded-full bg-gray-300 peer-checked:bg-blue-600\" />"

Toast notifications don't appear.

Ensure you have called AddMaraiUI() in Program.cs and that you have injected IToastService into your component. The toast container must also be present — add <MToastContainer /> to your root layout.

MDialog doesn't trap focus correctly.

Focus trapping requires the dialog panel to contain at least one focusable element. Add a close button inside MDialogContent using MDialogClose, or ensure a focusable child such as an input or button is present when the dialog opens.

MDataTable sorting doesn't work.

Column sorting requires the Sortable="true" attribute on each MDataTableColumn you want to be sortable, and the Property parameter must point to a comparable property on your model.

Version Notes

Where is the NuGet package?

Install with:

dotnet add package Marai.UI

Does Marai.UI require Tailwind CSS v4?

Yes. Marai.UI components assume Tailwind CSS v4 syntax in examples and the setup instructions use the @tailwindcss/cli package. Tailwind v3 projects will need to upgrade or adapt the build pipeline.