blazor-blueprint-ui

# 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](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](references/services.md) for: - `AddBlazorBlueprintComponents()` vs `AddBlazorBlueprintPrimitives()` - `ToastService` and `DialogService` - provider requirements and programmatic dialog usage Read [references/localization.md](references/localization.md) for: - `IBbLocalizer` and startup string overrides - `IStringLocalizer` integration patterns - culture-sensitive component text and formatting ### Icons Read [references/icons.md](references/icons.md) for icon component usage and styling guidance. ### Blueprints & Primitives Read [references/blueprints.md](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](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](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](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](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](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](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](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:** ```razor <BbTabs DefaultValue="overview">...</BbTabs> ``` **Controlled:** ```razor <BbTabs @bind-Value="currentTab">...</BbTabs> ``` ### Composition pattern ```razor <BbCard> <BbCardHeader><BbCardTitle>Title</BbCardTitle></BbCardHeader> <BbCardContent>Content</BbCardContent> <BbCardFooter>Actions</BbCardFooter> </BbCard> ``` ### AsChild pattern ```razor <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: 1. **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](references/patterns.md). 2. **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](references/setup.md). 3. **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](references/icons.md). 4. **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](references/blueprints.md). 5. **`BbProvider` must be the outermost wrapper** — Bootstrap order in `App.razor` matters: `<BbProvider>` wraps everything. See [setup.md § App.razor bootstrap order](references/setup.md). ## Workflow 1. **Read setup.md** for installation and providers. 2. **Choose components vs primitives** before building custom shells or behavior-heavy surfaces. 3. **Pick a category**: forms, layout/navigation, overlays, display/data, or charts. 4. **Load patterns.md** when composing multiple surfaces together. 5. **Load blueprints.md** when you need a production-shaped screen quickly. 6. **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](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](references/primitives.md) when markup ownership matters more than the default component styling.