Getting Started — Marai.UI

Requirements

Before installing Marai.UI, make sure your project meets the following prerequisites:

.NET 10.0 SDK or later
A Blazor Server, Blazor WebAssembly, or Blazor Web App project
Node.js and npm (for Tailwind CSS compilation)
Tailwind CSS v4.0 or later
Basic familiarity with Razor components

Tailwind CSS

Marai.UI components are beautiful by default — you can start building immediately without writing Tailwind classes. Tailwind is used when you want to customize layout, spacing, or visual overrides beyond the defaults. See Tailwind CSS Setup below.

Default Blazor Stylesheets

The default Blazor boilerplate includes Bootstrap or other built-in stylesheets. Remove or scope these to avoid visual conflicts with Marai.UI's design system.

Installation

Install Marai.UI from NuGet using the .NET CLI or the NuGet Package Manager.

.NET CLI

Run the following command in your project directory:

bash

dotnet add package Marai.UI

Make sure your project is targeting .NET 10 or the latest version. Using an older version of .NET may cause issues during installation.

Package Manager Console

powershell

Install-Package Marai.UI

PackageReference (csproj)

xml

<PackageReference Include="Marai.UI" Version="1.0.0" />

Setup

1. Register services

In your Program.cs, add the Marai.UI services to the DI container:

csharp

using Marai.UI.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// Add this line
builder.Services.AddMaraiUI();

var app = builder.Build();
// ...

2. Add global imports

Add the Marai.UI namespaces to your _Imports.razor so components are available across all pages without explicit @using statements. Each component lives in its own sub-namespace (e.g. Marai.UI.Components.MButton).

razor

@using Marai.UI.Components.MBadge
@using Marai.UI.Components.MButton
@using Marai.UI.Components.MCard
@using Marai.UI.Components.MInput
@using Marai.UI.Components.MLabel
@using Marai.UI.Components.MSeparator
@using Marai.UI.Components.MDialog
@using Marai.UI.Components.MDropdown
@using Marai.UI.Components.MPopover
@using Marai.UI.Components.MToast
@using Marai.UI.Components.MTooltip
@using Marai.UI.Components.MCheckbox
@using Marai.UI.Components.MRadioButton
@using Marai.UI.Components.MSelect
@using Marai.UI.Components.MSlider
@using Marai.UI.Components.MSwitch
@using Marai.UI.Components.MAccordion
@using Marai.UI.Components.MBreadcrumb
@using Marai.UI.Components.MDataTable
@using Marai.UI.Components.MDatePicker
@using Marai.UI.Components.MNav
@using Marai.UI.Components.MTabs
@using Marai.UI.Components.MAvatar
@using Marai.UI.Components.MCarousel
@using Marai.UI.Components.MSpinner
@using Marai.UI.Components.MStyleInjector
@using Marai.UI.Services
@using Marai.UI.Utilities

3. Include styles

To use Marai.UI's default theme, reference the stylesheet in your App.razor or layout:

html

<link rel="stylesheet" href="_content/Marai.UI/marai-ui.min.css" />

4. Include scripts

Add the Marai.UI JavaScript file to your App.razor:

html

<script src="_content/Marai.UI/marai-ui.js"></script>

5. Add MStyleInjector to your root layout

Place <MStyleInjector /> inside App.razor (or your root layout). This component renders the :root CSS variable block that powers all component colors. Without it, components will render unstyled even if AddMaraiUI() is registered.

razor

<MStyleInjector />

Why is this required?

AddMaraiUI() registers the theme resolver in DI but does not inject any CSS. <MStyleInjector /> is a Blazor component that reads the resolved colors and writes a <style> block into the page at render time. It must be present in the component tree.

Tailwind CSS Setup

Marai.UI components rely on Tailwind CSS utility classes. Follow these steps to set up Tailwind CSS in your Blazor project.

1. Install Tailwind CSS

Initialize npm in your project directory if you haven't already:

bash

npm init -y

Install Tailwind CSS as a development dependency:

bash

npm install -D tailwindcss @tailwindcss/cli

2. Create your CSS input file

Create a Styles/app.css file in your project root with the following content:

css

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

3. Add build script to package.json

Update your package.json to include build scripts:

json

{
  "scripts": {
    "build:css": "tailwindcss -i ./Styles/app.css -o ./wwwroot/tailwindcssv4.min.css --minify",
    "watch:css": "tailwindcss -i ./Styles/app.css -o ./wwwroot/tailwindcssv4.css --watch"
  }
}

If your package.json already has a scripts section, append the Marai.UI scripts below the existing ones:

json

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "build:css": "tailwindcss -i ./Styles/app.css -o ./wwwroot/tailwindcssv4.min.css --minify",
  "watch:css": "tailwindcss -i ./Styles/app.css -o ./wwwroot/tailwindcssv4.css --watch"
},

4. Integrate with MSBuild

Add the following to your .csproj file to automatically build Tailwind CSS during project compilation:

xml

<!-- Tailwind CSS build pipeline -->
<Target Name="BuildTailwindCss" BeforeTargets="Build">
  <Exec Command="npm run build:css" WorkingDirectory="$(ProjectDir)" />
</Target>

5. Reference the compiled CSS

In your App.razor or main layout file, add a reference to the compiled CSS:

html

<link rel="stylesheet" href="tailwindcssv4.min.css" />

Development Tip

During development, you can run npm run watch:css in a separate terminal to automatically rebuild your CSS whenever you make changes to your Razor files.

6. Verify the setup

Make sure your project is targeting .NET 10 or the latest version. Using an older version of .NET may cause the project build to fail.

xml

<TargetFramework>net10.0</TargetFramework>

Once verified, build your project to ensure Tailwind CSS compiles correctly:

bash

dotnet build

You should see Tailwind CSS build output in your build logs, and a wwwroot/tailwindcssv4.min.css file should be created with your compiled styles.

7. App.razor summary

After completing the steps above, your App.razor should include the following additions:

html

<link rel="stylesheet" href="_content/Marai.UI/marai-ui.min.css" />
<script src="_content/Marai.UI/marai-ui.js"></script>
<MStyleInjector />
<link rel="stylesheet" href="tailwindcssv4.min.css" />

Next steps

Colors — customize your application's color palette
Theming — CSS token overrides, dark mode, and data-state hooks
Browse all components — explore the full component library