Version v3 Documentation

You are viewing documentation for an older version. View latest (v4) documentation →

Installation

How to install and configure Blazor Blueprint in your Blazor application.

New Project (Recommended)

The fastest way to get started is with the official Blazor Blueprint project template. It creates a fully configured Blazor app with all dependencies, theming, and optional showcase pages.

# Install the template and create a new project
dotnet new install BlazorBlueprint.Templates
dotnet new blazorblueprint -n MyApp

Then run your new project:

cd MyApp
dotnet run

Template Options

Option	Default	Description
-n, --name	Required	Project name
-F, --Framework	net10.0	Target framework (net8.0, net9.0, or net10.0)
-R, --RenderMode	Auto	Render mode (Server, WebAssembly, or Auto)
-I, --IncludeShowcase	true	Include demo pages showing components

Examples:

# WebAssembly mode
dotnet new blazorblueprint -n MyApp -R WebAssembly

# Auto mode (Server then WASM)
dotnet new blazorblueprint -n MyApp -R Auto

# Without showcase pages
dotnet new blazorblueprint -n MyApp -I false

# Target .NET 10
dotnet new blazorblueprint -n MyApp -F net10.0

Adding to an Existing Project

Prerequisites

.NET 10 SDK (recommended) or .NET 8+ SDK
A Blazor project (Server, WebAssembly, or Hybrid)
Basic knowledge of Blazor and C#

Step 1: Install NuGet Packages

Install the Blazor Blueprint packages via NuGet Package Manager or the .NET CLI:

# Install Components (styled components - Primitives pulled in transitively)
dotnet add package BlazorBlueprint.Components

# Optional: Install Icons (packs: Lucide, Heroicons, Feather, FontAwesome)
dotnet add package BlazorBlueprint.Icons.Lucide

# Only if you want Primitives standalone (without the styled Components layer)
dotnet add package BlazorBlueprint.Primitives

Do I need BlazorBlueprint.Primitives?

BlazorBlueprint.Components already depends on BlazorBlueprint.Primitives, so you get the primitives automatically when you install Components. Only install Primitives explicitly if you want to use the unstyled primitives without the styled component layer on top.

Step 2: Configure Services

Add Blazor Blueprint services to your Program.cs:

Program.cs

using BlazorBlueprint.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// Add BlazorBlueprint services (primitives, toast, dialog)
builder.Services.AddBlazorBlueprintComponents();

var app = builder.Build();

// Configure the HTTP request pipeline...
app.Run();

Step 3: Add Stylesheets

Blazor Blueprint ships with pre-built CSS that includes all component styles. Add the following stylesheets to your App.razor or index.html:

App.razor

<!-- Theme variables (customize colors, radius, etc.) -->
<link href="css/theme.css" rel="stylesheet" />

<!-- Pre-built BlazorBlueprint styles (includes all component styles) -->
<link href="_content/BlazorBlueprint.Components/blazorblueprint.css" rel="stylesheet" />

Pre-built CSS

The blazorblueprint.css file is a fully compiled Tailwind CSS file that includes all styles for Blazor Blueprint components. You don't need to set up Tailwind CSS unless you want to use Tailwind utilities in your own code or customize the build.

Theme File

Create a theme file with CSS variables to customize colors. You can use the Theme Playground to generate this file, or start with the default theme:

wwwroot/css/theme.css

:root {
  /* Core colors using OKLCH color space */
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(1 0 0);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(1 0 0);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
}

* {
  border-color: var(--border);
}

body {
  background-color: var(--background);
  color: var(--foreground);
}

Step 4: Add Component Imports

Add using directives to your _Imports.razor:

_Imports.razor

@* All components and services *@
@using BlazorBlueprint.Components

@* Optional: Icons *@
@using BlazorBlueprint.Icons.Lucide.Components
@using BlazorBlueprint.Icons.Lucide.Data

Step 5: Add Providers to Your Layout

Blazor Blueprint ships a small set of root-level provider components. Add them to your root layout file so every page can use portal-based and service-driven components.

<BbPortalHost /> — required for components that use portals (Popover, Dialog, Sheet, Dropdown Menu, Combobox, Select, etc.).
<BbToastProvider /> — required if you use ToastService to show toast notifications. Accepts configuration like Position and ShowCountdown.
<BbDialogProvider /> — required if you use DialogService to open programmatic confirm dialogs. Not needed if you only use <BbDialog> declaratively.

MainLayout.razor

@inherits LayoutComponentBase

<div class="page">
    <main>
        @Body
    </main>
</div>

<!-- Required for portal-based components (Popover, Dialog, Select, etc.) -->
<BbPortalHost />

<!-- Required if you use ToastService to show toasts -->
<BbToastProvider />

<!-- Required if you use DialogService for programmatic confirm dialogs -->
<BbDialogProvider />

Important

Without <BbPortalHost />, components like Popover, Dialog, Combobox, and Select will not render their dropdown/overlay content properly. Make sure to add it to your root layout file. If you call ToastService or DialogService without their matching providers, nothing will render.

You're All Set!

You're now ready to start using Blazor Blueprint components in your application. Check out the Getting Started guide to learn how to use components, or browse the Components to see what's available.

Advanced Setup

Custom Tailwind CSS Setup

Only needed if you want to use Tailwind utilities in your own code or customize the CSS build.

When do you need this?

You want to use Tailwind utility classes like flex, p-4, text-primary in your own components
You want to customize the Tailwind configuration
You want smaller CSS bundles by only including utilities you actually use

1. Install Tailwind CSS CLI

Download the Tailwind CSS v4 standalone CLI for your platform. Select your operating system below:

Download the Windows executable and place it in your project root:

# Using PowerShell - download to project root
Invoke-WebRequest -Uri "https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-windows-x64.exe" -OutFile "tailwindcss.exe"

Or download manually from GitHub Releases (look for tailwindcss-windows-x64.exe).

2. Create CSS Input File

Create wwwroot/css/app-input.css using Tailwind v4 syntax:

wwwroot/css/app-input.css

/* Import Tailwind CSS v4 */
@import 'tailwindcss';

/* Import your theme file */
@import './theme.css';

/* Configure source paths for scanning Razor files
   (paths are relative to this file at wwwroot/css/app-input.css) */
@source "../../Pages";
@source "../../Shared";
@source "../../Components";

/* Class-based dark mode (matches theme toggle behavior) */
@custom-variant dark (&:where(.dark, .dark *));

/* Tailwind v4 CSS-first theme configuration.
   Maps CSS variables from the theme to Tailwind utility classes. */
@theme inline {
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --font-sans: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
  --font-mono: var(--font-mono, ui-monospace, monospace);
  --radius-lg: var(--radius);
  --radius-md: calc(var(--radius) - 2px);
  --radius-sm: calc(var(--radius) - 4px);
}

3. Add Build Integration

Add a build step to your project file to compile Tailwind CSS automatically:

.csproj

<Target Name="BuildTailwindCSS" BeforeTargets="BeforeBuild">
  <Message Text="Building Tailwind CSS..." Importance="high" />
  <Exec Command="tailwindcss.exe -i wwwroot/css/app-input.css -o wwwroot/css/app.css" />
</Target>

4. Add Your Compiled Stylesheet

Add your compiled Tailwind CSS alongside the pre-built Blazor Blueprint stylesheet. Keep both <link> tags when consuming Blazor Blueprint via NuGet. The order of the two <link> tags does not matter:

App.razor

<!-- Theme variables (customize colors, radius, etc.) -->
<link href="css/theme.css" rel="stylesheet" />

<!-- Pre-built BlazorBlueprint styles -->
<link href="_content/BlazorBlueprint.Components/blazorblueprint.css" rel="stylesheet" />

<!-- Your compiled Tailwind CSS (utilities for your own components) -->
<link href="css/app.css" rel="stylesheet" />

Why order doesn't matter

Blazor Blueprint ships every utility class wrapped in a dedicated CSS cascade layer named bb, declared as the strongest layer in the stylesheet (@layer properties, theme, base, components, utilities, bb;). Because layer priority is resolved before source order, component utilities like md:flex on the sidebar win the cascade regardless of which <link> tag the browser parses first. To override a Blueprint utility from your own CSS, use !important (which inverts layer priority) or write the override outside any @layer.

Why keep both stylesheets?

Tailwind v4 generates utility classes only from files it can scan via @source. When you install Blazor Blueprint through NuGet, the component .razor files ship as compiled DLLs and are not available for scanning, so your custom build cannot regenerate the component classes. The pre-built blazorblueprint.css already contains every class the components need, and it shares the same theme variables you define, so loading both is safe and produces no meaningful conflicts.

Replacing the pre-built stylesheet

You can drop the pre-built blazorblueprint.css only if you consume Blazor Blueprint as a project reference (source available) and add the component source paths to your @source directives so Tailwind can scan them. NuGet consumers should keep both stylesheets.

Previous Introduction Next Quick Start