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 overrides
IStringLocalizer 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.