# ComparisonBars (comparison-bars)

> Readable comparison rows on a shared zero-based scale, with optional emphasis.

- Entry: component
- Category: UI
- Preview capabilities: none (still preview)
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/comparison-bars
- JSON: https://jbm-ui.bns.studio/catalog/comparison-bars.json
- Registry item: https://jbm-ui.bns.studio/r/comparison-bars.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/comparison-bars
```

Also installs @jbm/tokens (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/comparison-bars.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/comparison-bars.tsx` | `src/jbm/ui/comparison-bars.tsx` | `@/jbm/ui/comparison-bars` |

## API

### `ComparisonBars` (component)

Description list of rows: label and formatted value on one line, then a 14px bar whose fill is value / max of the full width. Highlighted rows use vermilion for the value and fill; others use dim text and an ink fill. Bars are aria-hidden, so the text carries the data. Throws RangeError for negative or non-finite values, or a max that is not positive or below any value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `{ label: string; value: number; highlight?: boolean }[]` | required | Rows in display order: label, a finite nonnegative value, and optional highlight to mark the one emphasized row. |
| `max` | `number` | none | Shared scale ceiling. Defaults to the largest value (at least 1); set it to compare against a fixed range such as 100. |
| `formatValue` | `(value: number) => string` | `String` | Formats each value for its readout, e.g. (v) => `${v}%`. |

Also accepts React.HTMLAttributes<HTMLDivElement>.

## Stage

fluid: Width fills its container; bars span the full row width. Each row is about 40 stage pixels (15px label line, 4px row gap, 4px margin, 14px bar), with 20px between rows, so height grows with items. Long labels or values wrap and add lines.

## Examples

### Three rows on a 0–100 scale

```tsx
import { ComparisonBars } from "@/jbm/ui/comparison-bars"

<ComparisonBars max={100} formatValue={(v) => `${v} lecturas`} items={[
  { label: "Contexto", value: 42 },
  { label: "Una buena pregunta", value: 68 },
  { label: "Una idea clara", value: 90, highlight: true },
]} />
// Values must be nonnegative; max must cover all values.
```

## QA

- Check fills are proportional to value / max, a zero value shows an empty track, and a value equal to max fills the row.
- Only the highlighted row uses vermilion; keep a single highlight per figure.
- At narrow widths long labels wrap above their values and bars stay full width.
- Read without the bars (they are aria-hidden): each dt/dd pair still states the label and value.

## Docs

- [Visual primitives guide](https://jbm-ui.bns.studio/docs/visual-primitives.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
