# CompositionBar

One proportional bar with visible category amounts, shares or both.

Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.

## Example

```tsx
"use client";

import { FloodRoot, CompositionBar } from "@flood-md/react";
import "@flood-md/react/styles.css";

export function Example() {
  return (
    <FloodRoot>
      <CompositionBar label="Storage by file type" items={[
        {id:"originals", label:"Originals", value:54},
        {id:"exports", label:"Exports", value:24},
        {id:"backups", label:"Backups", value:14}
      ]} readout="both" formatValue={value => `${value} GB`} />
    </FloodRoot>
  );
}
```

## Design notes

- Use in a card or narrow panel to show a few mutually exclusive parts of one whole. Pass up to six finite nonnegative values with stable unique IDs and a meaningful label.
- The bar preserves category order and proportional segment widths. Keep that order consistent across views of the same categories. Use BarChart with layout="percent" to compare several totals.
- Choose inline readouts for short labels or rows for shared numeric alignment. Use value, share or both depending on what readers need. Exact readouts remain visible without pointer or keyboard interaction.
- Zero-valued categories stay in the list without taking bar width. All-zero data shows values and omits shares. An empty list uses emptyLabel.

## API reference

| Prop | Values | Default |
| --- | --- | --- |
| `label` | `string` | `Required` |
| `items` | `readonly DonutChartItem[]` | `Required` |
| `layout` | `"inline" \| "rows"` | `"inline"` |
| `readout` | `"value" \| "share" \| "both"` | `"value"` |
| `emptyLabel` | `string` | `"No data"` |
| `formatValue` | `(value: number) => string` | `—` |
| `formatShare` | `(share: number) => string` | `—` |
| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |
