Bit Field Explorer

A bit-field row visualisation for low-precision quantization. The continuous value snaps to the nearest bucket in the chosen format's grid — int8 and int4 lay down a uniform grid across range; fp16 and fp8 are a magnitude-spaced approximation, dense near zero and exponentially spaced further out. The active cell glows in cb-accent; the original / quantized / error readouts print beneath the row in mono so the snap-to-nearest behaviour is legible without colour.

Different from FloatBitViewer — that one shows the IEEE 754 sign / exponent / mantissa anatomy of a single number. This one shows the quantization buckets the value snaps to, the visual signature of fp16 / int8 inference.

Installation

npx shadcn@latest add https://craftbits.dev/r/bit-field-explorer.json

Usage

import { BitFieldExplorer } from "@craft-bits/core";
 
<BitFieldExplorer value={0.37} defaultFormat="int8" />

Drive the format from outside:

<BitFieldExplorer
  value={value}
  format={format}
  onFormatChange={setFormat}
  range={[-2, 2]}
/>

Compare the same value across formats:

<div className="space-y-6">
  <BitFieldExplorer value={0.37} defaultFormat="int8" />
  <BitFieldExplorer value={0.37} defaultFormat="int4" />
  <BitFieldExplorer value={0.37} defaultFormat="fp8" />
</div>

Anatomy

1. Two bucket models. Int formats lay down 2^bits evenly spaced buckets across range. FP formats are magnitude-spaced — dense near zero, doubling outward — a teachable approximation of the actual IEEE 754 / E5M2 / E4M3 layouts. Both share the same nearest-bucket interface so the row reads the same regardless of format.
2. Sub-sampled display. Int8 has 256 buckets; rendering them all would crush them below 2px on a phone. The component caps display cells per format (int8 to 64, int4 to 16, fp16 to 64, fp8 to 32) and samples evenly from the full grid. The row still represents the full quantized space, just sub-sampled for legibility; the header announces when sampling is active.
3. Snap-to-nearest highlight. The active cell (the bucket whose centre is closest to value) fills with cb-accent. Idle cells fade to 94% scale and 85% opacity so the highlight pops without being garish. The animation uses SPRINGS.smooth; prefers-reduced-motion: reduce collapses it to an instant swap.
4. Quantization error in mono. The footer prints the input value, the quantized value (centred on the active bucket), and the signed error. Non-zero error renders in cb-warning so the "your number doesn't fit cleanly" moment is visible at a glance.
5. Controlled or uncontrolled format. format plus onFormatChange for controlled, defaultFormat for uncontrolled — the Radix idiom. The format pills are a role="radiogroup" of role="radio" buttons with full keyboard support.

Props

Accessibility

• The outer element is role="figure" with an aria-label describing the format, the input value, the quantized value, and the signed error.
• The cell row is role="grid" with one row and aria-colcount equal to the bucket count. Each cell is a role="gridcell" with aria-selected set on the active bucket and an aria-label announcing the cell index and the bucket value.
• The format picker is a role="radiogroup" of role="radio" pills with aria-checked. Tab focuses the group; Space and Enter commit a selection.
• The readouts row is aria-live="polite" so screen readers hear the new quantized value and error whenever the input value or format changes.
• Colour is never the only signal: every readout has a textual label, and the active cell carries data-active="true" for assistive tooling and custom styling.
• The active-cell highlight respects prefers-reduced-motion: reduce and collapses to an instant swap when the user opts out.

Credits

• Extracted from: craftingattention (app/src/lessons/primitives/nn/BitFieldExplorer.tsx). The original was an IEEE 754 mantissa-toggle explorer (FP16 vs BF16, click bits on / off, watch tick marks appear on a number line) bound to a five-phase narration state machine. The library version reframes the same teaching surface as a quantization bucket grid — int8 / int4 / fp16 / fp8 buckets across a configurable range, with the input value snapped to the nearest cell and the quantization error printed in mono. That keeps the visual signature of low-precision inference but drops the project-specific phase narration, the bit-toggle interaction, and the inline raw colour vars in favour of cb-accent / cb-warning semantic tokens.