Architecture
Understanding the two-tier primitives architecture
Overview
BlazorUI follows the proven architecture pattern of Radix UI + shadcn/ui, adapted for Blazor. This separation between behavior and presentation provides maximum flexibility while maintaining beautiful defaults.
Two-Tier Architecture
Primitives Layer
Unstyled, headless components located in Primitives/.
- Handles all behavior and interaction logic
- Implements accessibility (ARIA, keyboard navigation)
- Manages component state
- Provides JavaScript interop where needed
- Zero styling - completely headless
Components Layer
Styled wrappers located in Components/.
- Wraps primitives with shadcn/ui styling
- Applies Tailwind utility classes
- Uses CSS variables for theming
- Provides beautiful defaults
- Zero behavioral logic
When to Use Each
Use Primitives When:
- ✓ Building a custom design system
- ✓ Need complete control over styling
- ✓ Want to apply your own CSS framework
- ✓ Creating unique visual designs
Use Components When:
- ✓ Want shadcn/ui design out of the box
- ✓ Need quick implementation
- ✓ Like the default styling
- ✓ Prefer convention over configuration
Infrastructure Services
Primitives are built on top of shared infrastructure services:
PortalService
Renders content outside DOM hierarchy
FocusManager
Focus trapping and restoration
PositioningService
Floating UI integration for positioning
IdGenerator
Unique IDs for ARIA relationships
Key Patterns
Controlled/Uncontrolled State
All primitives support both patterns - manage state internally or pass it from parent.
Composition via RenderFragment
Flexible component composition using Blazor's RenderFragment for maximum flexibility.
Context via CascadingValue
Component communication using Blazor's CascadingValue for clean parent-child relationships.
Accessibility
All primitives implement WCAG 2.1 AA standards by default:
- Full keyboard navigation (Tab, Enter, Space, Escape, Arrow keys)
- Automatic ARIA attributes (roles, labels, descriptions, states)
- Focus management with visual indicators
- Screen reader compatibility