BlazorBlueprint.Components 4.1.0-beta.2

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
This is a prerelease version of BlazorBlueprint.Components.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package BlazorBlueprint.Components --version 4.1.0-beta.2
                    


                    

                
NuGet\Install-Package BlazorBlueprint.Components -Version 4.1.0-beta.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="BlazorBlueprint.Components" Version="4.1.0-beta.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="BlazorBlueprint.Components" Version="4.1.0-beta.2" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="BlazorBlueprint.Components" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add BlazorBlueprint.Components --version 4.1.0-beta.2
                    


                    

                
#r "nuget: BlazorBlueprint.Components, 4.1.0-beta.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package BlazorBlueprint.Components@4.1.0-beta.2
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=BlazorBlueprint.Components&version=4.1.0-beta.2&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=BlazorBlueprint.Components&version=4.1.0-beta.2&prerelease
                    


                            Install as a Cake Tool

BlazorBlueprint.Components

Pre-styled Blazor components with shadcn/ui design. Beautiful defaults with zero configuration - no Tailwind setup required!

Features

  • Zero Configuration: Pre-built CSS included - no Tailwind setup required
  • shadcn/ui Design: Beautiful, modern design language inspired by shadcn/ui
  • Pre-Styled Components: Production-ready components with pre-built styling
  • Dark Mode: Built-in dark mode support using CSS variables
  • shadcn/ui Theme Compatible: Use any theme from shadcn/ui or tweakcn.com
  • Fully Customizable: Override styles with custom CSS or Tailwind classes
  • Built with Accessibility in Mind: Includes ARIA attributes and keyboard support via BlazorBlueprint.Primitives
  • Composable: Flexible component composition patterns
  • Type-Safe: Full C# type safety with IntelliSense support
  • .NET 10 minimum: v4 targets net10.0; .NET 8 and .NET 9 are no longer supported

Installation

Retarget your application to .NET 10 or later before upgrading to v4, and keep Components and Primitives on matching v4 versions. See the repository's migration guide and changelog.

dotnet add package BlazorBlueprint.Components

This package automatically includes:

  • BlazorBlueprint.Primitives - Headless primitives providing behavior and accessibility
  • BlazorBlueprint.Icons.Lucide - Lucide icon set
  • Pre-built CSS - No Tailwind setup required!

Quick Start

1. Register services in Program.cs:

builder.Services.AddBlazorBlueprintComponents();

This registers all required services including portal management, focus trapping, positioning, toast notifications, and programmatic dialogs.

2. Add to your _Imports.razor:

@using BlazorBlueprint.Components
@using BlazorBlueprint.Primitives

That's it — two imports give you access to all components and their enums (ButtonVariant, InputType, AccordionType, etc.).

3. Add CSS to your App.razor:

BlazorBlueprint Components come with pre-built CSS - no Tailwind setup required!

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />

    
    <link rel="stylesheet" href="styles/theme.css" />

    
    <link rel="stylesheet" href="_content/BlazorBlueprint.Components/blazorblueprint.css" />

    <HeadOutlet @rendermode="InteractiveServer" />
</head>
<body>
    <Routes @rendermode="InteractiveServer" />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

4. Add the portal host to your root layout (MainLayout.razor):

@using BlazorBlueprint.Primitives

<BbPortalHost />

This is required for overlay components (Dialog, Sheet, Popover, Tooltip, etc.) to render correctly.

If BlazorBlueprint.Primitives is not in scope, Razor does not treat the tag as a component — it emits a literal <bbportalhost> element, with no build error, and every overlay silently fails to render. In v3 the host lived in BlazorBlueprint.Primitives.Services; that using no longer resolves it.

5. Start using components:

<BbButton Variant="ButtonVariant.Default">Click me</BbButton>

<BbDialog>
    <BbDialogTrigger AsChild>
        <BbButton>Open Dialog</BbButton>
    </BbDialogTrigger>
    <BbDialogContent>
        <BbDialogHeader>
            <BbDialogTitle>Welcome to BlazorBlueprint</BbDialogTitle>
            <BbDialogDescription>
                Beautiful Blazor components with zero configuration
            </BbDialogDescription>
        </BbDialogHeader>
        <BbDialogFooter>
            <BbDialogClose AsChild>
                <BbButton Variant="ButtonVariant.Outline">Close</BbButton>
            </BbDialogClose>
        </BbDialogFooter>
    </BbDialogContent>
</BbDialog>

That's it! No Tailwind installation, no build configuration needed.

Available Components

General

Component Description
Accordion Collapsible content sections with smooth animations
Alert Contextual feedback messages with variant support
Alert Dialog Modal confirmation dialogs requiring user action
Aspect Ratio Maintain consistent width-to-height ratios
Avatar User profile images with fallback initials and group support
Badge Labels for status, categories, and metadata
Barcode Fourteen linear symbologies drawn as SVG, on encoders written in C# — Code 128/39, EAN-13/8, UPC-A, ITF, Codabar, ISBN, ISSN, MSI, Telepen, Pharmacode, POSTNET and Royal Mail 4-state
Breadcrumb Navigation breadcrumb trail with separator support
Button Interactive buttons with multiple variants and sizes
Button Group Grouped button controls with shared styling
Calendar Date selection calendar
Card Content container with header, content, and footer sections
Carousel Scrollable content carousel with navigation controls
Chart 14 chart types (Area, Bar, Candlestick, Funnel, Gauge, Heatmap, Line, Map, Pie, Radar, Radial Bar, Rose, Sankey, Scatter) on Apache ECharts with theme integration
Chip Selectable, dismissible pills, grouped with BbChipSet
Collapsible Expandable content area with trigger control
Copy Text Click-to-copy text with tooltip feedback and copied-state indicator
Dark Mode Toggle Button that toggles light/dark mode with customizable icons and optional label
Empty Empty state placeholder for no-content scenarios
Fab Floating action button for a screen's one main action
Highlighter Marks the parts of a text that matched a search
Image Image with a fallback for a source that will not load
Item List item container for menus and lists
Kbd Keyboard shortcut display
Link A link that sits on the text baseline
Notification Badge Accessible count or dot overlay for another element
Pagination Page navigation controls
Progress Progress indicator bar
QR Code Scannable code drawn as SVG on a from-scratch ISO/IEC 18004 encoder — all 40 versions, four error-correction levels, module shapes and a centre logo
Resizable Resizable panel layout with drag handles
Scroll Area Custom scrollable area with styled scrollbars
Scroll To Top Floating button that appears once the page has scrolled, and returns it to the top
Section Header Section heading with actions
Separator Visual dividers for content sections
Skeleton Loading placeholders for content and images
Spinner Loading spinner indicator
Split Button Button with dropdown action split
Stepper Progress through a sequence, with a BbStep for each stage
Theme Switcher Theme customization popover — light/dark mode, independent base and primary colors, and radius, with persistence
Timeline Chronological event display
Toggle Toggle button control
Toggle Group Single or multi-select toggle group
Tree View Hierarchical data display with selection, checkboxes, and keyboard navigation
Typography Typography components for consistent text styling

Overlays & Navigation

Component Description
App Bar Top bar with title and back actions, safe-area insets and touch-sized controls
Bottom Nav Safe-area bottom navigation with active links and touch-sized items
Command Command palette for quick actions and navigation
Context Menu Right-click context menus with items, labels, and shortcuts
Dialog Modal dialogs with backdrop and focus management
Drawer Slide-out drawer panels with header, footer, and items
Dropdown Menu Context menus with items, separators, and shortcuts
Exit Prompt Holds a navigation while there is unsaved work
Hover Card Rich preview cards on hover with delay control
Menubar Horizontal menu bar with dropdown menus
Navigation Menu Responsive navigation menu with submenus
Popover Floating panels for additional content and actions
Responsive Nav Mobile-responsive navigation
Sheet Side panels that slide in from viewport edges
Sidebar Responsive navigation sidebar with collapsible menus
Tabs Tabbed interface for organizing related content, with tabs the user can add, close, rename and reorder
Toast Toast notification system with action support
Tooltip Brief informational popups on hover or focus

Data & Enterprise

Component Description
Dashboard Grid Drag-and-drop, resizable widget layout for dashboards with responsive breakpoints and state persistence
Scheduler Day/week/work-week scheduling with Monday/Sunday week starts, configurable slots, resource lanes, drag/resize, event editing, confirmed deletion, recurrence and optional per-event IANA time zones
TreeSelect Searchable single/multiple hierarchy selection with cascading checkboxes, indeterminate states, leaf-only selection and form binding
Cascader Hierarchy columns, path search, leaf/branch selection, keyboard/RTL navigation and automatic scrolling to the active level
FileUpload Optional transport callback with progress, cancellation, retries and preserved browser files
DataGrid Enterprise data grid with sorting, filtering, row grouping, row/cell/batch editing, isolated drafts, validation, rejected-save recovery, selection, expandable rows, virtualization, and column management
DataTable Tables with sorting, filtering, pagination, and row selection
DataView List and grid layouts with sorting, filtering, pagination, and infinite scroll
Dynamic Form Schema-driven form rendering from JSON or code definitions
Filter Builder Visual query builder for data filter expressions with AND/OR logic and nested groups
Form Wizard Multi-step form wizard with progress tracking, per-step validation, and navigation controls
Dock IDE-style docking layout with drag-and-drop panels, pinning, maximize, pop-out floating windows, and tab overflow
Event Calendar Month, Week, and Agenda views over your own event model with per-event templates, styling, and click callbacks
Gantt A plan against a timeline: task list and bars in one table, six zoom levels, summary roll-up, milestones, dependency arrows, drag/resize/progress editing, row reordering and re-parenting, and right-to-left support
Pivot Data Grid Cross-tabulation with nested fields on both axes, totals worked out from the items, custom aggregates, drill-down and a field picker
Sortable Pointer and keyboard sortable lists/grids, connected-list transfer, move/drop permissions, reusable handles and custom drag previews

Form Controls

Component Description
Checkbox Binary selection control with indeterminate state
Checkbox Group Group of checkboxes with shared state management
Color Picker Color selection input
Combobox Autocomplete input with searchable dropdown
Currency Input Currency-formatted number input
Date Input Culture-ordered date segments with keyboard editing, calendar access and EditForm draft validation
Date Picker Date selection input with calendar popup
Date Range Picker Date range selection input
Date Time Picker Combined date and time selection in one popover
Field Form field wrapper with label, description, and error states
File Upload Drag-and-drop file selection with preview and optional upload progress, cancellation and retry
Input Text input fields with multiple types and sizes
Input Field Integrated input with field label and description
Input Group Grouped input controls with addons and buttons
Input OTP One-time password input with segmented fields
Label Accessible labels for form controls
List Box Always-visible list of options with the full listbox keyboard pattern, search, and single, multiple or range selection
Masked Input Input with mask pattern enforcement
Multi Select Multi-select dropdown with tag support
Native Select Native HTML select element with styling
Numeric Input Number input with formatting and validation
Pick List Two lists and the buttons that move options between them, with reordering, search and keyboard support
Quantity Stepper Touch-sized quantity editing with bounds and remove-at-minimum action
Radio Group Mutually exclusive options with keyboard navigation
Range Slider Dual-handle range slider input
Rating Star/icon rating input
Select Dropdown selection with groups and labels
Signature Signing field that captures a drawn or typed signature, with SVG, PNG and raw stroke output
Slider Single-handle slider input
Switch Toggle control for on/off states
Tag Input Inline tag/chip input for managing string lists with suggestions and validation
Textarea Multi-line text input field
Time Input Segmented 12/24-hour entry with optional seconds, bounds, picker and EditForm validation
Time Picker Time selection input

Editors

Component Description
Markdown Editor Markdown editor with toolbar and live preview
Rich Text Editor Rich text editor with formatting toolbar

Pre-Built Form Fields

Convenience wrappers that combine a form control with BbField for label, description, and error handling:

Component Description
FormFieldCascader Cascader with integrated field wrapper
FormFieldCheckbox Checkbox with integrated field wrapper
FormFieldCheckboxGroup CheckboxGroup with integrated field wrapper
FormFieldCombobox Combobox with integrated field wrapper
FormFieldCurrencyInput CurrencyInput with integrated field wrapper
FormFieldDateInput DateInput with integrated field wrapper
FormFieldDatePicker DatePicker with integrated field wrapper
FormFieldDateRangePicker DateRangePicker with integrated field wrapper
FormFieldDateTimePicker DateTimePicker with integrated field wrapper
FormFieldFileUpload FileUpload with integrated field wrapper
FormFieldInput Input with integrated field wrapper
FormFieldInputOTP InputOTP with integrated field wrapper
FormFieldMaskedInput MaskedInput with integrated field wrapper
FormFieldMultiSelect MultiSelect with integrated field wrapper
FormFieldNativeSelect NativeSelect with integrated field wrapper
FormFieldNumericInput NumericInput with integrated field wrapper
FormFieldQuantityStepper QuantityStepper with integrated field wrapper
FormFieldRadioGroup RadioGroup with integrated field wrapper
FormFieldSelect Select with integrated field wrapper
FormFieldSwitch Switch with integrated field wrapper
FormFieldTagInput TagInput with integrated field wrapper
FormFieldTextarea Textarea with integrated field wrapper
FormFieldTimeInput TimeInput with integrated field wrapper
FormFieldTimePicker TimePicker with integrated field wrapper
FormFieldTreeSelect TreeSelect with integrated field wrapper

Motion & Themes

Component Description
Height Animation Expansion, collapse and automatic content resizing while retaining child state
Motion Entrance/exit presets, custom keyframes, viewport/hover/press/manual triggers and reduced-motion handling
Page Transition Incoming navigation animation with a stable first render
Render State Provider Cascading prerender/interactive state
Screen Transition Keyed screen animations with a stable first render
Selection Indicator Animated active, hover and keyboard-focus feedback
Theme Scope Scoped density, typography, surfaces and menu appearance; floating overlays inherit the scope

Chat & AI

Component Description
Attachment File attachment chips with upload states (uploading, processing, error, done), previews, and actions
Bubble Message bubbles with tinted/outlined variants, reactions, and attachment slots
Marker Inline status and tool-call markers with an animated shimmer effect
Message Chat message rows with avatar, content, and footer, aligned per role

Services

Service Description
ToastService Toast notification state management
DialogService Programmatic dialog/confirm control
IPortalService Portal management for overlays (from Primitives)
IFocusManager Focus trapping and restoration (from Primitives)
IPositioningService Floating element positioning (from Primitives)
IKeyboardShortcutService Global keyboard shortcut registration (from Primitives)
DropdownManagerService Coordinates dropdown mutual exclusivity (from Primitives)

Component API Reference

Button

<BbButton
    Variant="ButtonVariant.Default"
    Size="ButtonSize.Default"
    Type="ButtonType.Button"
    IconPosition="IconPosition.Start"
    Disabled="false">
    Click me
</BbButton>
Parameter Type Default Values
Variant ButtonVariant Default Default, Destructive, Outline, Secondary, Ghost, Link
Size ButtonSize Default Small, Default, Large, Icon, IconSmall, IconLarge
Type ButtonType Button Button, Submit, Reset
IconPosition IconPosition Start Start, End

Input

<BbInput
    Type="InputType.Email"
    Placeholder="name@example.com"
    Disabled="false" />
Parameter Type Default Values
Type InputType Text Text, Email, Password, Number, Tel, Url, Search, Date, Time, File

Avatar

<BbAvatar Size="AvatarSize.Default">
    <BbAvatarImage Source="user.jpg" Alt="User" />
    <BbAvatarFallback>JD</BbAvatarFallback>
</BbAvatar>
Parameter Type Default Values
Size AvatarSize Default Small, Default, Large, ExtraLarge

Badge

<BbBadge Variant="BadgeVariant.Default">New</BbBadge>
Parameter Type Default Values
Variant BadgeVariant Default Default, Secondary, Destructive, Outline

Accordion

<BbAccordion Type="AccordionType.Single" Collapsible="true">
    <BbAccordionItem Value="item-1">
        <BbAccordionTrigger>Section 1</BbAccordionTrigger>
        <BbAccordionContent>Content 1</BbAccordionContent>
    </BbAccordionItem>
</BbAccordion>
Parameter Type Default Description
Type AccordionType Single Single (one item open) or Multiple (many items open)
Collapsible bool false When Single, allows closing all items

Tabs

<BbTabs
    DefaultValue="tab1"
    Orientation="TabsOrientation.Horizontal"
    ActivationMode="TabsActivationMode.Automatic">
    <BbTabsList>
        <BbTabsTrigger Value="tab1">Tab 1</BbTabsTrigger>
        <BbTabsTrigger Value="tab2">Tab 2</BbTabsTrigger>
    </BbTabsList>
    <BbTabsContent Value="tab1">Content 1</BbTabsContent>
    <BbTabsContent Value="tab2">Content 2</BbTabsContent>
</BbTabs>
Parameter Type Default Values
Orientation TabsOrientation Horizontal Horizontal, Vertical
ActivationMode TabsActivationMode Automatic Automatic (on focus), Manual (on click)

Sheet

<BbSheet>
    <BbSheetTrigger AsChild>
        <BbButton>Open Sheet</BbButton>
    </BbSheetTrigger>
    <BbSheetContent Side="SheetSide.Right">
        <BbSheetHeader>
            <BbSheetTitle>Sheet Title</BbSheetTitle>
            <BbSheetDescription>Sheet description</BbSheetDescription>
        </BbSheetHeader>
        
    </BbSheetContent>
</BbSheet>
Parameter Type Default Values
Side SheetSide Right Top, Right, Bottom, Left

Select

<BbSelect TValue="string" @bind-Value="selectedValue">
    <BbSelectTrigger>
        <BbSelectValue Placeholder="Select an option" />
    </BbSelectTrigger>
    <BbSelectContent>
        <BbSelectItem Value="@("option1")" Text="Option 1" />
        <BbSelectItem Value="@("option2")" Text="Option 2" />
    </BbSelectContent>
</BbSelect>

Select is a generic component. Specify TValue for type safety.

Separator

<BbSeparator Orientation="SeparatorOrientation.Horizontal" />
Parameter Type Default Values
Orientation SeparatorOrientation Horizontal Horizontal, Vertical

Skeleton

<BbSkeleton Shape="SkeletonShape.Rectangular" Class="w-full h-4" />
<BbSkeleton Shape="SkeletonShape.Circular" Class="w-12 h-12" />
Parameter Type Default Values
Shape SkeletonShape Rectangular Rectangular, Circular

DataTable

<BbDataTable TItem="User" Items="users" SelectionMode="DataTableSelectionMode.Multiple">
    <BbDataTableColumn TItem="User" Field="x => x.Name" Header="Name" />
    <BbDataTableColumn TItem="User" Field="x => x.Email" Header="Email" />
</BbDataTable>
Parameter Type Default Values
SelectionMode DataTableSelectionMode None None, Single, Multiple

Theming

BlazorBlueprint is 100% compatible with shadcn/ui themes. Customize your application's appearance using CSS variables.

Using Themes from shadcn/ui and tweakcn

You can use any theme from:

Simply copy the CSS variables and paste them into your wwwroot/styles/theme.css file.

Example Theme

Create wwwroot/styles/theme.css:

@layer base {
  :root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.1450 0 0);
    --primary: oklch(0.2050 0 0);
    --primary-foreground: oklch(0.9850 0 0);
    /* ... other variables */
  }

  .dark {
    --background: oklch(0.1450 0 0);
    --foreground: oklch(0.9850 0 0);
    --primary: oklch(0.9220 0 0);
    --primary-foreground: oklch(0.2050 0 0);
    /* ... other variables */
  }
}

Reference it in your App.razor before the BlazorBlueprint CSS:

<link rel="stylesheet" href="styles/theme.css" />
<link rel="stylesheet" href="_content/BlazorBlueprint.Components/blazorblueprint.css" />

Dark Mode

Dark mode automatically activates when you add the .dark class to the <html> element. All components will switch to dark mode colors.

Usage Example

<BbDialog>
    <BbDialogTrigger AsChild>
        <BbButton>Open Dialog</BbButton>
    </BbDialogTrigger>
    <BbDialogContent>
        <BbDialogHeader>
            <BbDialogTitle>Confirm Action</BbDialogTitle>
            <BbDialogDescription>
                Are you sure you want to proceed?
            </BbDialogDescription>
        </BbDialogHeader>
        <p>This action cannot be undone.</p>
        <BbDialogFooter>
            <BbDialogClose AsChild>
                <BbButton Variant="ButtonVariant.Outline">Cancel</BbButton>
            </BbDialogClose>
            <BbButton Variant="ButtonVariant.Default">Confirm</BbButton>
        </BbDialogFooter>
    </BbDialogContent>
</BbDialog>

AsChild Pattern

Use AsChild on trigger components to use your own styled elements instead of the default button:

<BbDropdownMenu>
    <BbDropdownMenuTrigger AsChild>
        <BbButton Variant="ButtonVariant.Outline">
            Actions
            <BbLucideIcon Name="chevron-down" Size="16" />
        </BbButton>
    </BbDropdownMenuTrigger>
    <BbDropdownMenuContent>
        <BbDropdownMenuItem>Edit</BbDropdownMenuItem>
        <BbDropdownMenuItem>Delete</BbDropdownMenuItem>
    </BbDropdownMenuContent>
</BbDropdownMenu>

This is the industry-standard pattern from Radix UI/shadcn/ui. When AsChild is true, the child component (e.g., BbButton) automatically receives trigger behavior via TriggerContext.

Form Example

<div class="space-y-4">
    <div>
        <BbLabel For="email">Email</BbLabel>
        <BbInput Id="email" Type="InputType.Email" Placeholder="name@example.com" />
    </div>

    <div class="flex items-center space-x-2">
        <BbCheckbox Id="terms" @bind-Checked="agreedToTerms" />
        <BbLabel For="terms">I agree to the terms and conditions</BbLabel>
    </div>

    <BbButton Disabled="@(!agreedToTerms)">Submit</BbButton>
</div>

@code {
    private bool agreedToTerms = false;
}

Customizing Components

Override Default Styles

Use the Class parameter to add custom CSS classes or Tailwind classes (if you have Tailwind set up):

<BbButton Class="bg-purple-600 hover:bg-purple-700">
    Custom Button
</BbButton>

<BbCard Class="border-2 border-purple-500 shadow-xl">
    Custom Card Styling
</BbCard>

Note: BlazorBlueprint Components include pre-built CSS and don't require Tailwind. However, you can still use Tailwind classes for customization if you've set up Tailwind in your project.

Classes you pass through Class come from your Tailwind build, not from blazorblueprint.css. Every utility the library ships is prefixed bb: (.bb\:flex, .bb\:sm\:hidden) and kept in its own cascade layer, so your build and the library's can never emit the same class name and their load order does not matter. The library strips its prefix when merging, so Class="p-6" still replaces the component's own bb:p-4. Do not @source this package from your Tailwind input — it finds only prefixed tokens and emits nothing. If you have no Tailwind build, the prefixed classes work anywhere on the page (class="bb:flex bb:gap-4"), but the set is whatever the components use and is not a stable API.

Component Composition

Build complex UIs by composing components:

<BbCard>
    <BbCardHeader>
        <BbCardTitle>Settings</BbCardTitle>
        <BbCardDescription>Manage your account settings</BbCardDescription>
    </BbCardHeader>
    <BbCardContent class="space-y-4">
        <div>
            <BbLabel>Email Notifications</BbLabel>
            <BbSwitch @bind-Checked="emailNotifications" />
        </div>
        <BbSeparator />
        <div>
            <BbLabel>Push Notifications</BbLabel>
            <BbSwitch @bind-Checked="pushNotifications" />
        </div>
    </BbCardContent>
    <BbCardFooter>
        <BbButton>Save Changes</BbButton>
    </BbCardFooter>
</BbCard>

Design Philosophy

BlazorBlueprint.Components follows the shadcn/ui philosophy with zero-configuration deployment:

  1. Zero Configuration: Pre-built CSS included - just install and use
  2. shadcn/ui Compatible: Uses the same design tokens and CSS variables
  3. Built on Primitives: All behavior comes from BlazorBlueprint.Primitives
  4. Theme Tokens: Fully themeable using CSS variables
  5. Built with Accessibility in Mind: Includes ARIA attributes and keyboard support
  6. Customizable: Override with custom CSS or add Tailwind if needed

When to Use

Use BlazorBlueprint.Components when:

  • Want beautiful defaults with shadcn/ui design
  • Need zero-configuration setup (no build tools required)
  • Want to ship quickly without building components from scratch
  • Need dark mode and theming support out of the box
  • Want shadcn/ui theme compatibility

Consider BlazorBlueprint.Primitives when:

  • Building a completely custom design system
  • Want zero opinions about styling
  • Need to match a specific brand or design language
  • Prefer full control over all CSS

Documentation

For full documentation, examples, and API reference, visit:

Dependencies

Optional:

  • Tailwind CSS (if you want to use Tailwind classes for customization)

License

Apache License 2.0 - see LICENSE for details.

The package includes LICENSE, NOTICE, and staticwebassets/THIRD-PARTY-NOTICES.txt. The bundled Tailwind CSS, tw-animate-css, ECharts, and Quill assets retain their upstream licenses, including the D3, ZRender, and Microsoft helper notices within ECharts. These notices are also available at _content/BlazorBlueprint.Components/THIRD-PARTY-NOTICES.txt. The world map boundaries are derived from Natural Earth, which is public domain.

Contributing

Contributions are welcome! Please see our Contributing Guide.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on BlazorBlueprint.Components:

Package Downloads
NEXCODE.Caffeine.UI

Shared Blazor UI Components — Blazor Blueprint, Plotly Charts, Localization
BlueprintShell

Embeddable Blazor shell built on BlazorBlueprint. Spin up a themed, dockable UI on a configurable port from any .NET application.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
4.1.0 0 9/22/2026
4.1.0-beta.2 0 9/22/2026
4.1.0-beta.1 32 9/21/2026
4.0.1 566 9/19/2026
4.0.0 52 9/19/2026
4.0.0-beta.10 37 9/19/2026
4.0.0-beta.9 41 9/18/2026
4.0.0-beta.8 48 9/17/2026
4.0.0-beta.5 69 9/16/2026
4.0.0-beta.4 40 9/16/2026
4.0.0-beta.3 74 9/15/2026
4.0.0-beta.2 56 9/15/2026
4.0.0-beta.1 51 9/15/2026
3.17.0 1,091 9/13/2026
3.16.1 160 9/12/2026
3.16.0 3,986 9/4/2026
3.15.0 21,800 8/5/2026
3.14.1 18,151 7/16/2026
3.14.0 905 7/15/2026
3.13.0 11,823 7/2/2026
Loading failed

## What's New in v4.1.0 (unreleased)

> **Prerelease preparation:** these cumulative notes describe the current v4.1.0 branch. The release script selects the package version.

### Breaking Changes

- **BbDateTimePicker**: `MinuteStep` must be between 1 and 59; invalid values now throw during parameter validation.
- **BbDockPanel**: panel IDs must be nonempty and unique within their dock layout; invalid registrations now throw.

- **BlazorBlueprint.Primitives**: the audit fixes require the matching Primitives build. Keep Components and Primitives on matching release versions, and see the Primitives release notes.
- **BbTabsTrigger**: Ctrl or Cmd with an arrow key, Home or End no longer moves focus to another tab. Ctrl or Cmd with an arrow key now moves the tab, and only when **BbTabsList** has `Reorderable` on and `OnMove` set. Otherwise it does nothing.
- **BbTooltipTrigger**, **BbHoverCardTrigger**: the Development-only AsChild warning now logs under the event name `TriggerContextUnconsumed` instead of `TooltipTriggerContextUnconsumed` and `HoverCardTriggerContextUnconsumed`, and its text changes. Update any log filter that matched the old names.
- **BbDataGrid**: the column resize module `js/datagrid-columns.js` is renamed `js/table-columns.js`, and each `<col>` now carries `data-column-id`. Only custom code that imported the old file directly needs to change.

### New Components

- **BbMapChart**, **BbMap**: a world choropleth chart with ISO country-code or English-name binding, automatic value-based coloring, `BbVisualMap` palette/range customization, no-data styling, tooltips, country clicks, and optional pan/zoom. World boundaries are bundled and loaded on demand; no API key is required.

- **BbGantt**, **BbGanttColumn**: a plan drawn against a timeline, with a task list, a bar per task and dependency arrows. It has six zoom levels, summary tasks that roll up dates and progress from their children, milestones, non-working-day shading and a today line. The chart draws dependencies but does not enforce them, so moving a task does not move the tasks after it.
- **BbGantt** editing: `AllowDrag`, `AllowResize`, `AllowProgressDrag`, `AllowLinking` and `AllowRowDrag` hand each change back through `OnTaskChange`, `OnDependencyCreate` and `OnTaskMove` rather than writing it, and each change can be refused. `ShowLegend`, `ShowTooltip`, sortable and resizable columns, and right-to-left pages are supported.
- **BbPivotDataGrid**, **BbPivotField**, **BbPivotValue**: row fields down the side, column fields across the top, and an aggregate where they cross. Totals and subtotals are worked out from every item under them, so an average total is a true average. `OnCellClick` gives the items behind a cell, `ShowFieldPicker` turns fields on and off, and paging never splits a row group.
- **BbQrCode**: a QR code drawn as SVG in the markup, with no JavaScript and no image request. It supports four error correction levels, `ModuleShape`, a centre `Image`, `ShowValue` and `AriaLabel`. The colours stay dark on light whatever the theme, and a value that is too long shows a message instead of throwing.
- **BbBarcode**: 14 barcode types drawn as SVG, including Code 128, Code 39, EAN-13, UPC-A, ISBN and POSTNET. Each type checks its characters, length and check digit, and an invalid value shows a message naming the problem instead of throwing. `ShowValue` prints the value as selectable text.
- **BbSignature**: sign by drawing or by typing a name. `@bind-Value` gives a `SignatureValue` with `Kind`, `Svg` and `Text`, and `GetPngAsync`, `GetPngBytesAsync` and `GetStrokesAsync` return the other forms on demand. The typed route is on by default because it is the accessible one; `AllowTyped="false"` removes it.
- **BbListBox**: an always-visible list of options with single (`@bind-Value`) or multiple (`@bind-Values`) selection, using the same `SelectOption<TValue>` as **BbSelect**. It has the full listbox keyboard pattern, `ShowSearch`, a `ShowSelectAll` that covers only the visible rows, `OptionDisabled`, `ItemTemplate` and `EditForm` validation.
- **BbPickList**: two **BbListBox** panes with move buttons between them. `Options` holds every option and `@bind-Values` holds the picked ones, in the order they were moved. The move-all buttons move only what the search leaves visible and skip disabled options, and `OnMove` reports what moved and which way.

### New Features

- **Accessible labels**: date/time pickers, selection controls, OTP input and file upload now expose `AriaLabel` on their interactive element; form wrappers forward it.
- **BbSectionHeader**: `HeadingLevel` selects h1 through h6, with h2 as the default.
- **Form wrappers**: checkbox groups, date ranges and file uploads support EditForm field expressions and field-change notifications. **BbMultiSelect** now has explicit `Required` and `ActiveClass` forwarding.

- **BbTabsList**: `Addable`, `Closable`, `Renamable` and `Reorderable`, each paired with a callback (`OnAdd`, `OnClose`, `OnRename`, `OnMove`). All are off by default, and a flag without its callback draws nothing. The tabs only ask, so you change the collection the tabs come from.
- **BbTabsTrigger**: `Closable`, `Renamable` and `Reorderable` override the list for one tab, for example to pin it. Delete or Backspace closes a tab, F2 or a double-click renames it, and setting `Cancel` on `TabRenameContext` reopens the editor with the typed text.

### Bug Fixes

- **BbDateRangePicker**: the mobile preset dropdown follows the selected calendar dates, including parent updates and desktop preset clicks. Unmatched/partial ranges show Custom, and clearing shows Select date range, so Today can always be selected when it is not the current range.
- **Radar tooltips**: data-derived indicator names, series names and values are HTML-escaped to prevent HTML injection.
- **BbSignature**: stroke restoration waits for the drawn pad to mount and initialize, including repeated restoration from typed mode.
- **BbPivotDataGrid**, **BbGantt**: changed parent headings and non-working-day bands redraw immediately. Gantt also renders initial build errors without requiring another parent interaction.
- **BbListBox**: the visible label supplies the accessible name, and navigation keys no longer consume the next Tab.
- **Charts**: click callbacks can be added, replaced and removed after initialization without remounting or changing chart data.
- **BbFileUpload**: explicitly setting bound `Files` to null clears the selection and releases removed resources; omitting `Files` still permits uncontrolled selection.

- **BbGantt**, **BbPivotDataGrid**: `OnBuilt` no longer loops when a parent handles it. Gantt waits for its rendered element before wiring JavaScript and preserves pending setup across deferred renders. **BbBarcode** displays encoder messages without framework resource keys on WebAssembly.
- **Tabs and steppers**: responsive tab lists support adding/reordering, and conditional steps follow their current markup order.
- **Dates and time**: blocked dates also apply to Now and empty-value time stepping; the first segment increment starts at its minimum; custom calendar day names update with parameters. Editable date inputs reflect EditForm validation state.
- **Selection and uploads**: required chip sets retain their last selected chip; toggle navigation accounts for changed disabled items; file-upload paste handling follows runtime `AllowPaste` changes.
- **ScrollToTop**: changed options and late/replaced targets are observed, focus is restored appropriately, and completion fires after reaching the top. **Motion** visibility changes only activate the Visibility trigger.
- **Rendering and callbacks**: pagination templates receive current state/options; signature empty-state reporting reflects restored strokes; message alignment and tinted bubble contrast are corrected.
- **Accessibility**: attachment actions have accessible names, decorative image fallbacks are hidden from assistive technology, and links announce a new tab only for `Target="_blank"`.
- **Chart colors**: explicit heatmap/candlestick series colors and map fill children are honored, with documented visual-map precedence.

- **BbDrawer**: `OpenChanged` now fires when `Open` is not bound. Before, a page that listened without binding `Open` heard nothing. It fires only on a real change, and a bound drawer is unchanged.

### Improvements

- **Localization**: sortable instructions and announcements, file-upload text/errors, AM/PM labels, and MultiSelect count/removal labels use `IBbLocalizer`.
- **Compatibility**: WholeWord retains word-start matching, Sidebar retains its controlled-mode callback requirement, and compact form-wrapper popup defaults remain unchanged.

- **BbRichTextEditor**: Quill 2.0.3 now ships inside the package and loads on first use, so the host page no longer needs Quill `<script>` or `<link>` tags. A host that loads its own Quill first keeps it. The package grows by about 214 KB of static assets.
- **AsChild triggers**: **BbCollapsibleTrigger**, **BbPopoverTrigger**, **BbDialogTrigger**, **BbDialogClose**, **BbSheetTrigger**, **BbSheetClose**, **BbDropdownMenuTrigger**, **BbAlertDialogTrigger**, **BbAlertDialogAction** and **BbAlertDialogCancel** now log a Development-only warning when nothing inside them reads the trigger context. Before, text or an icon inside such a trigger did nothing, and nothing said why.
- **BbDrawerTrigger**, **BbDrawerClose**: with `AsChild="true"`, log the same Development-only warning when the child cannot read the trigger context, such as a plain `<button>`.
- **Localization**: `DefaultBbLocalizer` adds default strings for the new components and the new tab actions.