BlazorBlueprint.Primitives 4.1.0

BlazorBlueprint.Primitives

Headless, unstyled Blazor primitive components with ARIA attributes and keyboard support. Build your own component library using these composable primitives.

Features

• Headless & Unstyled: Complete control over styling — primitives provide behavior, accessibility, and state management without imposing any visual design
• Built with Accessibility in Mind: Includes ARIA attributes and keyboard interaction support
• Composition-Based: Flexible component composition patterns for building complex UIs
• Type-Safe: Full C# type safety with IntelliSense support
• State Management: Built-in controlled and uncontrolled state patterns
• Keyboard Support: Keyboard interaction support for interactive components
• Two-Layer Portal Architecture: Category-scoped portals (Container and Overlay) for efficient rendering
• .NET 10: Built for the latest .NET platform

Installation

dotnet add package BlazorBlueprint.Primitives

Setup

Register services in Program.cs:

builder.Services.AddBlazorBlueprintPrimitives();

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

<BbPortalHost />

Add a single import to _Imports.razor:

@using BlazorBlueprint.Primitives

Reference the primitives stylesheet from your host page (App.razor or index.html):

<link rel="stylesheet" href="_content/BlazorBlueprint.Primitives/css/primitives.css" />

It is small and carries no design decisions — only the rules the primitives' own markup depends on, such as hiding screen-reader-only announcements and sizing the dismiss overlay. Skip it and the Sortable list reads its keyboard instructions out as visible body text. Apps that also use BlazorBlueprint.Components can load it or not; the two stylesheets agree.

Available Primitives

Services

API Reference

Accordion

<BbAccordion Type="AccordionType.Single" Collapsible="true" DefaultValue="item-1">
    <BbAccordionItem Value="item-1">
        <BbAccordionTrigger>Section 1</BbAccordionTrigger>
        <BbAccordionContent>Content 1</BbAccordionContent>
    </BbAccordionItem>
</BbAccordion>

Checkbox

<BbCheckbox @bind-Checked="isChecked" Indeterminate="@isIndeterminate">
    <BbCheckboxIndicator />
</BbCheckbox>

BbCheckboxIndicator renders the appropriate check or indeterminate SVG icon automatically based on parent state:

Select

<BbSelect TValue="string" @bind-Value="selected" @bind-Open="isOpen">
    <BbSelectTrigger>
        <BbSelectValue Placeholder="Choose..." />
    </BbSelectTrigger>
    <BbSelectContent>
        <BbSelectItem Value="@("a")" Text="Option A" />
        <BbSelectItem Value="@("b")" Text="Option B" />
    </BbSelectContent>
</BbSelect>

Select uses [CascadingTypeParameter] — child components infer TValue from the parent. Supports ItemClass for parent-level item styling.

Dialog

<BbDialog @bind-Open="isOpen">
    <BbDialogTrigger>Open</BbDialogTrigger>
    <BbDialogPortal>
        <BbDialogOverlay />
        <BbDialogContent>
            <BbDialogTitle>Title</BbDialogTitle>
            <BbDialogDescription>Description</BbDialogDescription>
            <BbDialogClose>Close</BbDialogClose>
        </BbDialogContent>
    </BbDialogPortal>
</BbDialog>

Sheet

<BbSheet>
    <BbSheetTrigger>Open</BbSheetTrigger>
    <BbSheetPortal>
        <BbSheetOverlay />
        <BbSheetContent Side="SheetSide.Right">
            <BbSheetTitle>Title</BbSheetTitle>
            <BbSheetDescription>Description</BbSheetDescription>
            <BbSheetClose>Close</BbSheetClose>
        </BbSheetContent>
    </BbSheetPortal>
</BbSheet>

Popover

<BbPopover>
    <BbPopoverTrigger>Open</BbPopoverTrigger>
    <BbPopoverContent Side="PopoverSide.Bottom" Align="PopoverAlign.Center">
        Content here
    </BbPopoverContent>
</BbPopover>

Tooltip

<BbTooltip DelayDuration="700" HideDelay="0">
    <BbTooltipTrigger>Hover me</BbTooltipTrigger>
    <BbTooltipContent>Tooltip text</BbTooltipContent>
</BbTooltip>

HoverCard

<BbHoverCard OpenDelay="700" CloseDelay="300">
    <BbHoverCardTrigger>Hover for preview</BbHoverCardTrigger>
    <BbHoverCardContent>Rich preview content</BbHoverCardContent>
</BbHoverCard>

Dropdown Menu

<BbDropdownMenu ItemClass="px-2 py-1.5 cursor-pointer rounded hover:bg-accent">
    <BbDropdownMenuTrigger>Menu</BbDropdownMenuTrigger>
    <BbDropdownMenuContent>
        <BbDropdownMenuItem>Cut</BbDropdownMenuItem>
        <BbDropdownMenuItem>Copy</BbDropdownMenuItem>
        <BbDropdownMenuItem Href="https://example.com" Target="_blank">Visit Site</BbDropdownMenuItem>
        <BbDropdownMenuCheckboxItem @bind-Checked="isEnabled">Enable</BbDropdownMenuCheckboxItem>
    </BbDropdownMenuContent>
</BbDropdownMenu>

BbDropdownMenuItem supports Href and Target for link items — renders as <a> when Href is set.

Switch

<BbSwitch @bind-Checked="isEnabled" class="relative h-6 w-11 rounded-full bg-input">
    <BbSwitchThumb class="pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg" />
</BbSwitch>

BbSwitchThumb automatically syncs data-state ("checked" / "unchecked") from the parent via cascading parameter.

Radio Group

<BbRadioGroup TValue="string" @bind-Value="selected" ItemClass="flex items-center gap-2">
    <BbRadioGroupItem Value="@("a")">Option A</BbRadioGroupItem>
    <BbRadioGroupItem Value="@("b")">Option B</BbRadioGroupItem>
</BbRadioGroup>

Tabs

<BbTabs DefaultValue="tab1" Orientation="TabsOrientation.Horizontal"
        ActivationMode="TabsActivationMode.Automatic">
    <BbTabsList>
        <BbTabsTrigger Value="tab1">Tab 1</BbTabsTrigger>
    </BbTabsList>
    <BbTabsContent Value="tab1">Content</BbTabsContent>
</BbTabs>

Table

<BbTable TData="Person">
    <BbTableHeader>
        <BbTableRow>
            <BbTableHeaderCell>Name</BbTableHeaderCell>
            <BbTableHeaderCell>Email</BbTableHeaderCell>
        </BbTableRow>
    </BbTableHeader>
    <BbTableBody>
        @foreach (var person in people)
        {
            <BbTableRow>
                <BbTableCell>@person.Name</BbTableCell>
                <BbTableCell>@person.Email</BbTableCell>
            </BbTableRow>
        }
    </BbTableBody>
</BbTable>

Portal Architecture

Primitives use a two-layer portal system for rendering overlay content:

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

Each category has its own host (BbContainerPortalHost, BbOverlayPortalHost), so opening a tooltip doesn't cause Dialog portals to re-render. BbPortalHost is a convenience wrapper that renders both.

BbFloatingPortal keeps content mounted in the DOM when closed (ForceMount defaults to true), hidden via CSS. A data-state attribute ("open" / "closed") on the portal content enables CSS animations.

JavaScript Modules

Every primitive that needs JavaScript gets it from one bundle, js/primitives/bb-primitives.js, loaded through PrimitiveModules:

var module = await PrimitiveModules.GetAsync(JSRuntime);
await module.InvokeVoidAsync("elementUtils.scrollIntoView", elementId, "nearest");

The identifier is namespace.function, where the namespace is the module's file name in camelCase — clickOutside, elementUtils, positioning, focusTrap, and so on. The individual files are still importable on their own if you need just one.

overlay.open is the one to reach for when adding a floating component: it positions, reveals, keeps the element positioned and wires the dismissal listeners in a single call. Splitting that back into separate awaits puts a network round trip between each step, on every open.

From a component, declare what you want rather than wiring it — BbFloatingPortal forwards it:

<BbFloatingPortal Dismiss="@(new FloatingDismissOptions {
                      ContentId = Context.ContentId,
                      TriggerId = Context.TriggerId,
                      OnOutsideInteraction = true,
                      OnEscapeKey = true })"
                  OnDismiss="@HandleDismiss">

The portal reports the gesture and does nothing else with it; what a dismissal means stays with the owner.

Two rules matter if you add a primitive that needs JavaScript:

• Re-export the new module from bb-primitives.js. A module reached by its own import(...) from C# costs an extra circuit round trip on Blazor Server, every page load, cached or not.
• Do not dispose what GetAsync returns. It is shared by every component on the circuit. The returned reference ignores disposal so that a mistake here cannot break anything, but the call is still dead code.

Controlled vs Uncontrolled

All stateful primitives support both controlled and uncontrolled modes:

Uncontrolled (Component manages its own state)

<BbDialog>
    <BbDialogTrigger>Open</BbDialogTrigger>
    <BbDialogPortal>
        <BbDialogOverlay />
        <BbDialogContent>Content</BbDialogContent>
    </BbDialogPortal>
</BbDialog>

Controlled (Parent component manages state)

<BbDialog @bind-Open="isDialogOpen">
    <BbDialogTrigger>Open</BbDialogTrigger>
    <BbDialogPortal>
        <BbDialogOverlay />
        <BbDialogContent>
            <button @onclick="() => isDialogOpen = false">Close</button>
        </BbDialogContent>
    </BbDialogPortal>
</BbDialog>

@code {
    private bool isDialogOpen = false;
}

Design Philosophy

BlazorBlueprint.Primitives follows the "headless component" pattern popularized by Radix UI and Headless UI:

1. Separation of Concerns: Primitives handle behavior and accessibility; you handle the design
2. Composability: Build complex components by composing simple primitives
3. No Style Opinions: Zero CSS included — bring your own design system
4. Accessibility by Default: ARIA attributes and keyboard navigation built-in

When to Use

Use BlazorBlueprint.Primitives when:

• Building a custom design system from scratch
• Need complete control over component styling
• Want to match a specific brand or design language
• Integrating with existing CSS frameworks or design tokens

Consider BlazorBlueprint.Components when:

• Want beautiful defaults with shadcn/ui design
• Prefer zero-configuration setup with pre-built CSS
• Need to ship quickly without custom styling

Documentation

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

• Documentation Site
• GitHub Repository

License

Apache License 2.0 - see LICENSE for details.

The package includes LICENSE, NOTICE, and staticwebassets/THIRD-PARTY-NOTICES.txt. The bundled Floating UI and SortableJS assets retain their MIT licenses. These notices are also available at _content/BlazorBlueprint.Primitives/THIRD-PARTY-NOTICES.txt.

Contributing

Contributions are welcome! Please see our Contributing Guide.