BlazorBlueprint.Primitives 3.16.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 8: 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

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.

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.

Contributing

Contributions are welcome! Please see our Contributing Guide.