| name | blazor-blueprint-ui |
| description | Build and customize .NET 8+ Blazor UIs with BlazorBlueprint. Use when choosing between BlazorBlueprint.Components and BlazorBlueprint.Primitives, wiring setup and providers, using ToastService/DialogService/localization, selecting icon packs, applying shadcn-ui-style theming, or copying and adapting BlazorBlueprint blueprints. |
| metadata | {"version":"0.3.0","author":"arisng","lastVerified":"2026-07-08T00:00:00.000Z","libraryVersion":"3.13.0"} |
BlazorBlueprint UI
Build modern Blazor web applications using the current BlazorBlueprint component library.
Repository: https://github.com/blazorblueprintui/ui
Documentation: https://blazorblueprintui.com
Original Source: https://blazorblueprintui.com/llms.txt
Full Bundle: https://blazorblueprintui.com/llms/llms-full.txt
Examples in the refreshed references use the official upstream Bb* naming.
Package Overview
Core packages:
- BlazorBlueprint.Components - Styled component library; includes primitives
- BlazorBlueprint.Primitives - Headless accessibility and behavior layer
- BlazorBlueprint.Icons.Lucide - Lucide icon pack (1,753 icons)
- BlazorBlueprint.Icons.Heroicons - Heroicons pack (1,288 icons)
- BlazorBlueprint.Icons.Feather - Feather icon pack (286 icons)
- BlazorBlueprint.Icons.FontAwesome - Font Awesome 6 Free pack (2,066 icons, 3 variants)
Quick Navigation
Setup & Installation
Read references/setup.md for:
- NuGet installation and service registration
- CSS, imports, and provider setup
BbPortalHost, BbToastProvider, and BbDialogProvider- Theme variables and dark mode
- Verification and troubleshooting
Services & Localization
Read references/services.md for:
AddBlazorBlueprintComponents() vs AddBlazorBlueprintPrimitives()ToastService and DialogService- provider requirements and programmatic dialog usage
Read references/localization.md for:
IBbLocalizer and startup string overridesIStringLocalizer integration patterns- culture-sensitive component text and formatting
Icons
Read references/icons.md for icon component usage and styling guidance.
Blueprints & Primitives
Read references/blueprints.md for:
- category routing across auth, sidebar, apps, dashboards, forms, data, marketing, and ecommerce
- the upstream blueprint catalog and per-category files
- copy/adapt workflow for production-shaped screens
Read references/primitives.md for:
- when to stay on
BlazorBlueprint.Components
- when to switch to
BlazorBlueprint.Primitives
- headless behavior and custom design-system guidance
Common Patterns
Read references/patterns.md for:
- controlled vs uncontrolled state
EditForm + BbField conventions- root provider patterns
- dashboard / app shell defaults
- blueprint-first acceleration
Component Categories
Form Components (30+ form-related)
Read references/components-forms.md for:
- text, typed, and structured inputs
- selection controls and searchable selection
- date/time, date+time, and OTP flows
- uploads, editors, and advanced inputs
- form sections, wizards, dynamic forms, and
BbFormField* wrappers
Layout & Navigation Components (15+)
Read references/components-layout.md for:
- sidebars, responsive nav, navigation menus, and breadcrumbs
- cards, tabs, accordions, collapsible content, and IDE-style docking
- resizable work areas, scroll areas, separators, and aspect-ratio containers
- routing guidance for shells vs display/data surfaces
Overlay Components (14+)
Read references/components-overlays.md for:
- dialogs, alert dialogs, sheets, drawers, and popovers
- menus, tooltips, hover cards, and command surfaces
DialogService and ToastService usage- provider and portal requirements
Display & Data Components (18+)
Read references/components-display-data.md for:
- alerts, badges, avatars, shortcuts, loading states, and empty states
- items, timelines, typography, carousel, click-to-copy, and chat components
BbDataTable, BbDataGrid, and BbDataView routing- dashboard/data-screen and event calendar guidance
Chart Components (12 types)
Read references/components-charts.md for:
- the current Apache ECharts-based chart stack
BbChart composite charts and ChartConfig- dedicated bar, line, area, pie, radial bar, gauge, radar, scatter, and candlestick charts
BbChartContainer and chart theming
Counts are approximate and grow with each library release. The authoritative component list is at https://blazorblueprintui.com/llms/llms-full.txt.
Key Architecture Patterns
Controlled vs uncontrolled state
Uncontrolled:
<BbTabs DefaultValue="overview">...</BbTabs>
Controlled:
<BbTabs @bind-Value="currentTab">...</BbTabs>
Composition pattern
<BbCard>
<BbCardHeader><BbCardTitle>Title</BbCardTitle></BbCardHeader>
<BbCardContent>Content</BbCardContent>
<BbCardFooter>Actions</BbCardFooter>
</BbCard>
AsChild pattern
<BbDialog>
<BbDialogTrigger AsChild>
<BbButton Variant="ButtonVariant.Destructive">Delete</BbButton>
</BbDialogTrigger>
<BbDialogContent>...</BbDialogContent>
</BbDialog>
Note: AsChild defaults to true (v3+). Set AsChild="false" when you need the trigger's built-in <button> wrapper instead of merging into a child element — useful when migrating v2 code that relied on auto-generated wrappers.
Portal and provider pattern
Overlay components render through BbPortalHost. App-wide toasts and service-driven dialogs also need BbToastProvider and BbDialogProvider in the root layout.
Known Pitfalls
These are hard-won constraints — check them before generating any BB component code:
-
CaptureUnmatchedValues is supported, not universal — Most BB components now accept arbitrary HTML attributes (@onclick, style, class, data-*, etc.) and pass them through to the root element. However, not every component declares [Parameter(CaptureUnmatchedValues = true)] — check the upstream docs or source for your specific component. For components that lack it, use a wrapper element. See patterns.md § Unmatched attribute capture.
-
Tailwind subset only — BB ships only the utilities its own components use; writing other Tailwind classes silently has no effect. Add missing utilities as custom CSS. See setup.md § Tailwind subset limitation.
-
Lucide icon names change — Several names have been renamed upstream (e.g. check-circle → circle-check, home → house). A broken icon renders ⚠️. Verify names at https://blazorblueprintui.com/llms/icons/lucide.txt. See icons.md § Renamed icons.
-
Auth pages are SSR-only — Login/signup blueprints use [ExcludeFromInteractiveRouting]. Use HTML form POST + [SupplyParameterFromForm]; do not add @rendermode InteractiveServer. See blueprints.md § Auth pages and SSR.
-
BbProvider must be the outermost wrapper — Bootstrap order in App.razor matters: <BbProvider> wraps everything. See setup.md § App.razor bootstrap order.
Workflow
- Read setup.md for installation and providers.
- Choose components vs primitives before building custom shells or behavior-heavy surfaces.
- Pick a category: forms, layout/navigation, overlays, display/data, or charts.
- Load patterns.md when composing multiple surfaces together.
- Load blueprints.md when you need a production-shaped screen quickly.
- Style through theme variables and validate dark mode.
When to Load References
- setup.md: first-time setup, providers, theming, dark mode, icons import questions
- services.md: DI registration differences,
ToastService, DialogService, provider requirements
- localization.md: label overrides,
IBbLocalizer customization, culture-sensitive component text
- blueprints.md: rapid auth, sidebar, dashboard, data, marketing, or ecommerce screen scaffolding
- primitives.md: headless composition, custom design systems, or behavior-only reuse
- components-forms.md: editing flows, validation, selection, wizards, schema-driven forms
- components-layout.md: shells, responsive navigation, cards, tabs, resizable work areas
- components-overlays.md: dialogs, menus, tooltips, command palettes, toasts
- components-display-data.md: alerts, status display, tables, grids, data views, empty/loading states
- components-charts.md: dashboards, KPI visuals, mixed/composite chart composition
- patterns.md: cross-component conventions and blueprint-first workflows
Blueprints and Primitives
- Blueprints provide ready-to-copy compositions for auth, sidebar shells, dashboards, forms, data screens, marketing, and ecommerce. Read references/blueprints.md for category routing and upstream blueprint entry points.
- Primitives are the headless layer for advanced users who want BlazorBlueprint behavior without the styled component surface. Read references/primitives.md when markup ownership matters more than the default component styling.
