Prerequisites

Three things, and there is deliberately no fourth. The library is a NuGet package with static web assets: no npm install, no bundler step, no JavaScript framework underneath it.

The .NET 8, 9 or 10 SDK One package multi-targets all three, so moving the app to a newer framework never means changing the reference.

A Blazor app WebAssembly, Server, Hybrid (MAUI) or static SSR - the same markup and the same parameters render under all four.

Nothing to build The stylesheet and the script ship inside the package as static web assets. There is no Node toolchain to install and nothing to compile.

Starting a brand new app? dotnet new bit-empty produces a solution with every step below already done - see Start from a template.

1. Install the package

One package carries the whole core library. Pick whichever of the three routes matches how you work.

.NET CLI

Package Manager

PackageReference

Run this in the directory of the project your components live in:

dotnet add package Bit.BlazorUI

In a Blazor Web App with a separate .Client project, the package belongs to whichever project holds your .razor files - which is usually both of them.

Optional packages

Four more packages exist so that an app only ships the parts it asked for. Every component page says which package that component comes from.

Package	Add it when
Bit.BlazorUI.Extras(opens in a new tab)	You use one of the heavier components - `BitDataGrid`, `BitChart`, `BitMap`, `BitPdfViewer`, the markdown and rich-text editors - or one of the Fluent 2, Material and Cupertino design-system presets.
Bit.BlazorUI.Icons(opens in a new tab)	You want the icons. The core package embeds only the two dozen glyphs its own components draw with - a 3 KB font subset - and this one adds the full Fabric (MDL2) set that `BitIconName` names, browsable on the iconography page.
Bit.BlazorUI.Assets(opens in a new tab)	Your users may not have Segoe UI or Roboto installed - the fonts behind the Fluent and Material type ramps - or you want the `Script` and `Link` components that fingerprint an asset by its content.
Bit.BlazorUI.Legacy(opens in a new tab)	You are upgrading a project that used the previous chart, data grid, editors or PDF reader - see Legacy components.

Add whichever of them you need:

dotnet add package Bit.BlazorUI.Extras
dotnet add package Bit.BlazorUI.Icons
dotnet add package Bit.BlazorUI.Assets
dotnet add package Bit.BlazorUI.Legacy

Each brings its own stylesheet - and Extras and Legacy their own script - which step 4 links.

2. Import the namespace

One using, stated once, so that no page has to repeat it.

Add this line to the _Imports.razor of every project that has .razor files - in a Blazor Web App with a WebAssembly client, that is the server project and the .Client project both:

@using Bit.BlazorUI

Every component the library ships lives in this one namespace. If a BitButton comes back as the type or namespace name could not be found, this is the line missing from that project.

3. Register the services

A few things the library does are driven from C# rather than from markup - opening a modal, switching the theme - and those are resolved from dependency injection.

Add this to Program.cs, beside the rest of your registrations:

builder.Services.AddBitBlazorUIServices();

It registers five services:

BitModalService - opens a modal from C# instead of from markup.
BitThemeManager - switches preset, toggles dark mode, overrides tokens at runtime.
BitThemeNotifications - raises ThemeChanged when any of that happens.
BitExternalThemeLoader - pulls a preset stylesheet in on demand.
BitPageVisibility - the browser's page-visibility state, as an event.

In a Blazor Web App with a WebAssembly client, call it in both Program.cs files. A component that renders on the server during prerendering and again in the browser afterwards has to find the service in both containers.

The optional packages register on top

Each of these calls the core registration itself, so the one that matches your packages replaces the line above rather than joining it:

builder.Services.AddBitBlazorUIExtrasServices(); // Bit.BlazorUI.Extras
builder.Services.AddBitBlazorUILegacyServices(); // Bit.BlazorUI.Legacy

All three registrations take a trySingleton flag that registers the eligible services once for the process instead of once per scope:

builder.Services.AddBitBlazorUIServices(trySingleton: true);

Turn it on for WebAssembly and Hybrid (MAUI) only - the hosting models where the process serves exactly one user. Do not enable it on Blazor Server: BitModalService holds per-circuit rendering state, and a singleton would share it across circuits, leaking one visitor's modal into another's browser.

4. Add the styles and scripts

One stylesheet and one script, shared by the whole library. Which file they go in is the only thing that differs between hosting models.

Open the file that matches your app:

Your app	The file to open
Blazor Web App (.NET 8+)	`Components/App.razor`
Standalone WebAssembly	`wwwroot/index.html`
Blazor Hybrid (MAUI)	`wwwroot/index.html`
Blazor Server (.NET 6 / 7)	`Pages/_Host.cshtml` or `Pages/_Layout.cshtml`

The stylesheet goes in <head>, and the script at the end of <body>, after the Blazor script:

<head>
    ...
    <link href="_content/Bit.BlazorUI/styles/bit.blazorui.css" rel="stylesheet" />
</head>
<body>
    ...
    <script src="_framework/blazor.web.js"></script>
    <script src="_content/Bit.BlazorUI/scripts/bit.blazorui.js"></script>
</body>

Order matters among the stylesheets. A design-system preset is an override-only bundle of --bit-* tokens, so anything that re-skins the library - Fluent 2, Material, Cupertino, or a block of your own - has to be linked after the core stylesheet. One linked before it does nothing at all.

Add only the lines for the packages you installed in step 1, in this order:

<!-- in head -->
<link href="_content/Bit.BlazorUI/styles/bit.blazorui.css" rel="stylesheet" />
<link href="_content/Bit.BlazorUI.Extras/styles/bit.blazorui.extras.css" rel="stylesheet" />
<link href="_content/Bit.BlazorUI.Legacy/styles/bit.blazorui.legacy.css" rel="stylesheet" />
<link href="_content/Bit.BlazorUI.Icons/styles/bit.blazorui.icons.css" rel="stylesheet" />
<link href="_content/Bit.BlazorUI.Assets/styles/bit.blazorui.assets.css" rel="stylesheet" />

<!-- at the end of body -->
<script src="_content/Bit.BlazorUI/scripts/bit.blazorui.js"></script>
<script src="_content/Bit.BlazorUI.Extras/scripts/bit.blazorui.extras.js"></script>
<script src="_content/Bit.BlazorUI.Legacy/scripts/bit.blazorui.legacy.js"></script>

The Fluent 2, Material and Cupertino presets ship with Bit.BlazorUI.Extras as one stylesheet each, linked after the core one. The theming page has them, together with what each token controls.

5. Render your first component

The setup is done. This is how you confirm it - and what a wrong answer here tells you.

Paste this into any page:

<BitButton IconName="@BitIconName.Add">Click me</BitButton>

<BitTextField Label="Your name" Placeholder="Name" @bind-Value="name" />

<BitDatePicker Label="Pick a date" />

<BitToggle Label="Notifications" DefaultValue="true" />

@code {
    private string? name;
}

Rendered result Live on this page, from the markup above

Your name

Pick a date

Notifications

If the controls come out looking like plain unstyled HTML, the stylesheet from step 4 is not reaching the browser. If they look right but the date picker's calendar never opens, it is the script. Troubleshooting has the rest of the symptoms.

Everything below this point is optional. The next thing worth reading is not on this page: it is theming, which is where the library stops looking like the default and starts looking like your product.

Browse the components

Make it yours

Start from a template

Or skip all five steps: two commands produce a solution with the packages referenced, the services registered and the host file already written.

bit Blazor Empty

A clean solution wired for theming, static SSR and responsive layouts - the shortest path from nothing to a page of your own. Install the template once:

dotnet new install Bit.BlazorEmpty

Then create an app from it:

dotnet new bit-empty -n MyBitBlazorApp

bit Boilerplate

The same wiring plus what a real product needs on day one - identity, an API, a database, localization, and the Android, iOS, macOS and Windows heads of one codebase:

dotnet new install Bit.Boilerplate
dotnet new bit-bp -n MyBitProject

Both are dotnet new templates rather than dependencies: what they produce is your source, with no runtime tie back to them.

Cache busting

Worth doing before your first deployment rather than after it. Without it, the browser of someone already using your app keeps serving them the previous version of the library's css and js.

On .NET 9 or later, the built-in @Assets[""] feature fingerprints the resource files for you.

bit BlazorUI also publishes its own version, which you can append as a query string:

<script src="_content/Bit.BlazorUI/scripts/[email protected]"></script>

Note: that expression only works in App.razor. For other root files - index.html in a standalone WebAssembly project, for instance - the version has to be added another way.

Bit.BlazorUI.Assets(opens in a new tab) ships two drop-in components for App.razor that hash the file's actual content, so the URL changes exactly when the file does - and only then.

Script - a replacement for <script>:

<Script Src="_content/Bit.BlazorUI/scripts/bit.blazorui.js"></Script>

renders as:

<script src="_content/Bit.BlazorUI/scripts/bit.blazorui.js?v=sha256-Z5yBv0K89OBRVurhAVzatpp3aGXsNn00e3GzQiTq_Z4"></script>

Link - a replacement for <link>:

<Link Href="_content/Bit.BlazorUI/styles/bit.blazorui.css" rel="stylesheet" />

renders as:

<link href="_content/Bit.BlazorUI/styles/bit.blazorui.css?v=sha256-VI6BIGZLTtmyhn3V-4RH-Yyi0Ud3p0g5dHvByeaoZ9Y" rel="stylesheet" />

This very site uses both - see its App.razor (opens in a new tab).

Troubleshooting

Nearly everything that goes wrong in the first hour is one of these seven, and each of them points back at the step it came from.

The components render, but look like plain unstyled HTML

The stylesheet from step 4 is missing or is not being served. Look for bit.blazorui.css in the browser's network tab: a 404 there means the path is wrong, or that the app is not serving static web assets at all - app.MapStaticAssets() on .NET 9 and later, app.UseStaticFiles() before that.

Dropdowns, callouts and pickers never open

bit.blazorui.js is missing, or its URL 404s. Everything that has to measure or position something in the live document - callouts, dropdowns, pickers, tooltips - goes through it, so the components still render without it and simply do nothing when clicked.

Icons come out as empty boxes

The core package embeds only the glyphs its own components draw with. Any other BitIconName needs the Bit.BlazorUI.Icons package and its stylesheet - one half without the other is what produces the box.

The type or namespace name 'BitButton' could not be found

@using Bit.BlazorUI is missing from that project's _Imports.razor. In a Blazor Web App it has to be in the .Client project's copy too - step 2.

There is no registered service of type 'BitModalService'

Or BitThemeManager, or any of the other three: AddBitBlazorUIServices() has not run in the container that rendered the component. Under prerendering there are two of those, so the call belongs in both Program.cs files - step 3.

A Material or Cupertino preset changes nothing

A preset is an override-only bundle of --bit-* tokens, so its stylesheet has to be linked after the core one, and the matching bit-theme value has to be set on <html>. The theming page covers both.

Your users still see the previous version's styles after a deploy

Their browser is holding the old css and js. That is what cache busting exists to prevent, and it is the one step that is much easier to add before the first deployment than after it.

Something else? Ask in discussions(opens in a new tab) - the team develops the library on the same repository, so the answer comes from the people who wrote it.

AI and MCP integration

Point your coding agent at the library's MCP server and it discovers components, pulls accurate examples, and follows the library's conventions on its own.

This documentation site is also an MCP server: the component catalog, every parameter table, the worked examples and the theming reference are exposed as tools a coding agent can call, answered from the packages this deployment actually references rather than from what a model half-remembers. The endpoint is https://blazorui.bitplatform.dev/mcp(opens in a new tab), and it works with GitHub Copilot, Cursor, Claude, Windsurf and anything else that speaks MCP.

The MCP server page carries the setup - the mcp.json for each client and the rules to add to your agents.md - and is a working client for the server besides: it talks to this very deployment and shows both halves of every exchange.

Connect your agent

Legacy components

Only if you are upgrading a project that used the previous implementations of Chart, DataGrid, the editors or the PDF reader.

Some of the older components were re-implemented with new APIs - the native SVG BitChart, the new BitDataGrid, BitMarkdownViewer, BitMarkdownEditor, BitRichTextEditor and BitPdfViewer. Their previous versions are preserved unchanged in Bit.BlazorUI.Legacy(opens in a new tab), under their own namespace, so the two generations can live side by side without conflict.

The package ships:

BitChartLegacy - the original Chart.js based charting component.
BitDataGridLegacy - the original data grid (previously renamed to BitQuickGrid).
BitMarkdownViewerLegacy - the original marked.js based markdown viewer.
BitMarkdownEditorLegacy - the original markdown editor.
BitRichTextEditorLegacy - the original Quill based rich text editor.
BitPdfReaderLegacy - the original pdf.js based PDF reader.

1. Install the package:

dotnet add package Bit.BlazorUI.Legacy

2. Import the namespace in _Imports.razor:

@using Bit.BlazorUI.Legacy

3. Register its services (this also registers the core bit BlazorUI services):

builder.Services.AddBitBlazorUILegacyServices();

4. Add its stylesheet and script:

<link href="_content/Bit.BlazorUI.Legacy/styles/bit.blazorui.legacy.css" rel="stylesheet" />
<script src="_content/Bit.BlazorUI.Legacy/scripts/bit.blazorui.legacy.js"></script>

What's next

The setup is behind you. These are the four pages that take an install to a finished product.

Components All 99 of them, each with live examples and its full API table. Theming Design tokens, the four presets, dark mode and scoped overrides - where it starts looking like your product. Iconography The full Fabric (MDL2) set, searchable, with every name one click from your clipboard. MCP server Give your coding agent the real API instead of a half-remembered one.

Getting started