DOCSEARCHbyAlgolia
Submit Docs

Blazor Blueprint UI Library

repository·main·Indexed 19 days ago

https://github.com/blazorblueprintui/ui

A modern UI library for Blazor providing accessible, design-system-first components and headless primitives. Inspired by shadcn/ui and designed for Tailwind CSS and .NET 8 render modes, it includes styled components, headless primitives for custom styling, enterprise-grade components (like DataGrid and Dashboard Grid), AI chat interface building blocks, and support for multiple icon libraries including Lucide, Heroicons, Feather, and FontAwesome.

Tokens
46.1K
Snippets
151
Records
200
Agent score
67%

What's inside Blazor Blueprint

  1. Explore Enterprise Components

    main

    Blazor Blueprint provides a suite of high-level, production-ready components designed for complex, data-driven enterprise applications. These components handle advanced logic like state persistence, drag-and-drop, and complex data sourcing out of the box.

    Key Enterprise components include:

    • Dashboard Grid: A resizable, drag-and-drop widget layout built on CSS Grid with responsive breakpoints.
    • DataGrid: A full-featured grid supporting multi-column sorting, filtering, row grouping, virtualization, and various data sources (IQueryable, IEnumerable, or ItemsProvider).
    • Dynamic Form: A schema-driven component that generates complete forms (including validation and conditional visibility) from a definition object.
    • Filter Builder: A visual query builder for constructing complex AND/OR logic expressions.
    • Form Wizard: A multi-step navigation component with progress indicators and per-step validation.
    • Chart: 11 chart types (Area, Bar, Candlestick, etc.) powered by Apache ECharts.
    • Dock: An IDE-style layout for managing draggable and pinnable panels.
    • Event Calendar: A calendar for managing event models with Month, Week, and Agenda views.
    • Editors: Includes both WYSIWYG (Rich Text) and Markdown editors with live previews.

  2. How the Portal Architecture works

    main

    BlazorBlueprint.Primitives uses a two-layer portal system to render overlay content, separating full-screen overlays from floating elements to optimize rendering performance. Each category has its own dedicated host:

    • Container portals (PortalCategory.Container): Used by Dialog and Sheet for full-screen overlays.
    • Overlay portals (PortalCategory.Overlay): Used by Popover, Select, Dropdown, Tooltip, and HoverCard for positioned floating content.

    Key Components:

    • BbContainerPortalHost: The host for container-type portals.
    • BbOverlayPortalHost: The host for overlay-type portals.
    • BbPortalHost: A convenience wrapper that renders both host types.
    • BbFloatingPortal: Keeps content mounted in the DOM even when closed (via ForceMount, which defaults to true) and hides it using CSS. It uses a data-state attribute ("open" or "closed") on the content to facilitate CSS animations.

  3. Use different Heroicon variants

    main

    You can switch between four different visual styles using the Variant parameter of type HeroIconVariant:

    • HeroIconVariant.Outline: 24x24, stroke-based (Default)
    • HeroIconVariant.Solid: 24x24, filled
    • HeroIconVariant.Mini: 20x20, filled
    • HeroIconVariant.Micro: 16x16, filled
    <HeroIcon Name="camera" Variant="HeroIconVariant.Outline" />
<HeroIcon Name="camera" Variant="HeroIconVariant.Solid" />
<HeroIcon Name="camera" Variant="HeroIconVariant.Mini" />
<HeroIcon Name="camera" Variant="HeroIconVariant.Micro" />

  4. How BlazorBlueprint Chart Components work

    main

    BlazorBlueprint charts use a Recharts-inspired composition pattern. Instead of a single monolithic component, you build charts by nesting specialized child components (like <XAxis>, <YAxis>, <Line>, etc.) inside a parent chart component (like <LineChart>).

    Key Concepts:

    • Declarative API: Compose complex charts using nested Blazor components.
    • Reflection-based Data Binding: Pass any IEnumerable to the chart and use the DataKey property on child components to reference specific properties by name.
    • Automatic Theme Support: The library uses CSS custom properties (e.g., --chart-1 through --chart-5) and a MutationObserver to automatically re-render when the application switches between light and dark modes.
    • Responsiveness: Every chart instance uses a ResizeObserver to handle container resizing automatically.
    <LineChart Data="@data" Height="300px">
    <XAxis DataKey="month" />
    <YAxis />
    <ChartTooltip />
    <Line DataKey="desktop" Name="Desktop" Color="var(--chart-1)" />
</LineChart>

  5. Use headless primitives for custom styling

    main

    Blazor Blueprint provides 26 headless primitives that handle complex interaction logic—such as focus trapping, ARIA attributes, keyboard shortcuts, and portal rendering—without any default styling. Use these when you need full design freedom or are building a custom design system. You can apply your own CSS, Tailwind classes, or inline styles directly to the primitive components.

    <BbAccordion class="my-accordion">
    <BbAccordionItem Value="item-1">
        <BbAccordionTrigger class="my-trigger">Section One</BbAccordionTrigger>
        <BbAccordionContent class="my-content">Content here.</BbAccordionContent>
    </BbAccordionItem>
</BbAccordion>

  6. Understand the two-layer Portal architecture

    main

    The portal system has been redesigned into two categories to optimize re-rendering: Container and Overlay.

    Categories

    • PortalCategory.Container: Used for Dialog, Sheet, and AlertDialog.
    • PortalCategory.Overlay: Used for Popover, Select, Dropdown, Tooltip, and HoverCard.

    Host Components

    • BbContainerPortalHost: Renders only Container portals.
    • BbOverlayPortalHost: Renders only Overlay portals.
    • BbPortalHost: The legacy host that renders both categories internally.

    IPortalService API Changes

    If you implement a custom IPortalService, you must update the following methods:

    • RegisterPortal(string id, RenderFragment content, PortalCategory category)
    • GetPortals(PortalCategory category)
    • event Action<PortalCategory>? OnPortalsCategoryChanged

  7. Understand FloatingPortal ForceMount behavior

    main

    The BbFloatingPortal now keeps portal content mounted in the DOM even when closed (ForceMount defaults to true). Instead of unmounting, content is hidden via CSS and repositioned when re-opened.

    Key details for developers:

    • CSS Animations: A data-state attribute ("open" or "closed") is applied to the portal content div, allowing you to use CSS exit animations (e.g., data-[state=closed]:animate-out).
    • Immediate Resolution: Because items are always registered in the portal, Select display text resolves immediately without needing manual cache-seeding or workarounds.
    • Affected Components: This affects Select, Popover, Tooltip, HoverCard, and DropdownMenu.

  8. Understand the AsChild pattern

    main

    The AsChild pattern is used on trigger components (like BbDropdownMenuTrigger or BbSheetTrigger) to allow you to use your own styled elements (like a BbButton) instead of the default trigger. When AsChild is set to true, the child component automatically receives the necessary trigger behavior via TriggerContext.

    <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>

  9. Build Chat and AI interfaces

    main

    Blazor Blueprint includes specialized building blocks for creating AI-agent and chat interfaces:

    • Message: Chat rows that align content based on the sender's role (e.g., user vs. assistant), including avatars and footers.
    • Bubble: Message bubbles with support for tinted/outlined variants, reactions, and attachment slots.
    • Attachment: File attachment chips that track upload states (uploading, processing, error, done) and provide previews.
    • Marker: Inline status indicators (e.g., "searching the web...") using an animated shimmer effect to represent tool calls or background processing.

  10. Leverage CascadingTypeParameter for generic components

    main

    In v3, Select<TValue>, CheckboxGroup<TValue>, and ToggleGroup<TValue> use the [CascadingTypeParameter] attribute. This means you only need to specify the TValue on the root parent component; all child components (like BbSelectTrigger, BbSelectItem, BbCheckboxGroupItem, or BbToggleGroupItem) will automatically infer the type.

    Example: Select

    <BbSelect TValue="string" @bind-Value="selectedFruit">
    <BbSelectTrigger class="...">
        <BbSelectValue Placeholder="Select a fruit" />
    </BbSelectTrigger>
    <BbSelectContent class="...">
        <BbSelectItem Value="apple" Text="Apple" />
        <BbSelectItem Value="banana" Text="Banana" />
    </BbSelectContent>
</BbSelect>

    Example: CheckboxGroup

    <BbCheckboxGroup TValue="string" @bind-Values="_selected">
    <BbCheckboxGroupItem Value="@("Apple")" Label="Apple" />
    <BbCheckboxGroupItem Value="@("Banana")" Label="Banana" />
</BbCheckboxGroup>

    Example: ToggleGroup

    <BbToggleGroup TValue="string" @bind-Value="_alignment" Type="ToggleGroupType.Single">
    <BbToggleGroupItem Value="@("left")">Left</BbToggleGroupItem>
    <BbToggleGroupItem Value="@("center")">Center</BbToggleGroupItem>
    <BbToggleGroupItem Value="@("right")">Right</BbToggleGroupItem>
</BbToggleGroup>

  11. Understand the Blazor Blueprint two-layer architecture

    main

    Blazor Blueprint is organized into two layers:

    1. BlazorBlueprint.Components: Pre-styled, ready-to-use components that ship with CSS matching the shadcn/ui design system. No Tailwind setup is required.
    2. BlazorBlueprint.Primitives: Headless components that provide ARIA attributes, focus management, and keyboard support without any styling. These are used for building custom designs.

    To use the full suite, register both layers. To use only headless logic, register only the Primitives.

  12. Configure Accessibility for FeatherIcons

    main

    When using icons, follow these accessibility patterns:

    1. Decorative Icons: If the icon is placed next to text that already describes the action, it is considered decorative and does not need a label.

      <button>
    <FeatherIcon Name="camera" />
    <span>Take Photo</span>
</button>

    2. Semantic/Icon-Only Icons: If the icon is the only content within an interactive element (like a button), you must provide an AriaLabel so screen readers can identify the action.

      <button>
    <FeatherIcon Name="camera" AriaLabel="Take Photo" />
</button>
    <button>
    <FeatherIcon Name="camera" AriaLabel="Take Photo" />
</button>