Getting started
One package and one service registration - then plain Razor components that render semantic HTML with the
keyboard, focus and ARIA wiring done, and nothing else. Bheadless ships no CSS: every state is a
data-* or ARIA attribute your own stylesheet, Tailwind or design system styles.
Install
In a Blazor Web App with an interactive client, the package belongs in the .Client project,
next to the pages that use it.
dotnet add package Bit.Bheadless
Register the services
It registers BitBhInterop, the scoped wrapper around the library's script, the live-region
announcer IBitBhAnnouncer and the toast queue BitBhToaster. The components fall back
to sensible defaults without it, but register it anyway - in a Blazor Web App in both Program.cs
files, because the pages are prerendered on the server before they run in the browser.
// Program.cs - in every project that renders the components
builder.Services.AddBitBheadlessServices();
And the namespace, in _Imports.razor:
@using Bit.Bheadless
bit-bheadless.js, is
loaded by a Razor class library initializer. The components need an interactive render mode
to respond to input; prerendered, they render their initial, accessible markup.
A first component
A component family is a parent and its parts: BitBhDisclosure owns the open state and cascades it
to BitBhDisclosureButton and BitBhDisclosurePanel, which render a
<button> and a <div> with aria-expanded,
aria-controls and data-state already set. The classes are yours.
<BitBhDisclosure class="disclosure">
<BitBhDisclosureButton class="disclosure-button">
<Template Context="d">
@(d.IsOpen ? "Hide details" : "Show details")
<span class="disclosure-chevron @(d.IsOpen ? "open" : "")" aria-hidden="true">▾</span>
</Template>
</BitBhDisclosureButton>
<BitBhDisclosurePanel class="disclosure-panel">
<div class="disclosure-body">...</div>
</BitBhDisclosurePanel>
</BitBhDisclosure>
.disclosure-button {
display: flex;
justify-content: space-between;
width: 100%;
}
.disclosure-button[data-state="open"] {
background: var(--color-fill);
}
.disclosure-button:focus-visible {
outline: 2px solid var(--color-focus);
}
.disclosure-chevron.open {
transform: rotate(180deg);
}
[data-state="open"] directly. Reach for a
part's Template, as the chevron does here, only when the markup itself depends on the state.
Core concepts
| Concept | In Bheadless |
|---|---|
| Compound components | A parent owns the state and cascades it to its parts: BitBhMenu and its BitBhMenuButton, BitBhMenuItems and BitBhMenuItems. ChildContent is always a plain RenderFragment, so parts nest freely inside an EditForm, a panel or each other. |
| State | Every stateful part is controlled (@bind-Value), uncontrolled (DefaultValue, DefaultOpen) or uncontrolled and notified (OnValueChange). |
| Template | A part's Template hands its child content the part's state - IsOpen, IsActive, IsSelected - for markup that depends on it. |
| Common parameters | As renders another element, Id overrides the generated one (the aria-* references follow it) and Ref hands over the element. Any other attribute - class, style, data-*, aria-*, an @onclick - is forwarded and merged. |
| Styling hooks | data-state, data-active, data-highlighted, data-selected, data-disabled, data-invalid, data-orientation, data-anchor and the ARIA states they mirror. |
| Positioning | Floating parts take an Anchor - a placement such as "bottom start" or a BitBhAnchorOptions with gap, flip, shift and size matching - and expose the measured sizes as --bit-bh-* CSS variables. |
| Overlays | Escape and outside clicks dismiss the topmost layer only, and OnDismissRequest can cancel it. Modals trap focus, make the rest of the page inert, lock scrolling and give focus back on close; closing parts stay mounted until their exit animation ends. |
| Announcements | IBitBhAnnouncer speaks through a shared polite / assertive live region - the command palette's result counts and the toasts use it, and so can your own code. |
| Right-to-left | BitBhDirectionProvider (or Dir on a component) mirrors the horizontal arrow keys. |
Plain CSS or Tailwind
Every component page on this site comes twice: once styled with hand-written CSS, once with Tailwind v4
utilities and data-* variants. The switcher at the top of a page moves between the two; the
components and their markup are the same in both.
<BitBhMenuItem class="rounded px-2 py-1 data-highlighted:bg-blue-50 data-disabled:opacity-50">Edit</BitBhMenuItem>
<BitBhTab class="border-b-2 border-transparent data-[state=active]:border-blue-600">Profile</BitBhTab>A strict Content-Security-Policy
A few components set styles of their own (a visually hidden label's clipping, a slider thumb's position).
Under a policy whose style-src has no 'unsafe-inline', turn on strict CSP mode: the
components then render no style attribute and the runtime applies their styles through the CSSOM,
which such a policy allows. The script in <head> applies them before the prerendered page is
first painted. With WebAssembly or Auto rendering, turn it on in both Program.cs files, the
server's and the client's, like the registration itself: the pages are prerendered on the server and then run
in the browser.
// Program.cs
builder.Services.AddBitBheadlessServices(configureOptions: options => options.StrictCsp = true);
<!-- App.razor, in <head> -->
<script src="_content/Bit.Bheadless/bit-bheadless-csp.js"></script>