# VolumeProfile (/docs/charts/volume-profile)

VolumeProfile answers "at which _level_ did activity concentrate — not when?". It is a histogram turned perpendicular to
the usual trend axis: the level runs vertically and bars extend horizontally by the mass of activity at each level. The
modal level — the point of control, or POC — is accented, and the value area (the levels holding most of the activity)
is shaded.

```tsx
import { VolumeProfile } from "@microcharts/react/volume-profile";

const profile = [ { level: 134, weight: 3 }, { level: 136, weight: 6 }, { level: 138, weight: 11 }, { level: 140,
weight: 18 }, { level: 142, weight: 26 }, { level: 144, weight: 20 }, { level: 146, weight: 12 }, { level: 148, weight:
7 }, { level: 150, weight: 4 }, ];

<VolumeProfile data={profile} title="Volume by price" />
```

## Install

```tsx
import { VolumeProfile } from "@microcharts/react/volume-profile";

<VolumeProfile data={profile} title="Volume by price" />
```

Setup (package + stylesheet): [Quickstart](/docs/quickstart#set-up-with-an-ai-agent) or paste [`/agent-setup.md`](/agent-setup.md) into your agent.


## When to use it

- **Good for** — volume-at-price, level-of-activity distributions, load by tier.
- **Avoid for** — a time series (Sparkline) or when the timing is what matters.


## Variants

```tsx
<VolumeProfile
  data={[
    { level: 138, weight: 11 },
    { level: 140, weight: 18 },
    { level: 142, weight: 26 },
    { level: 144, weight: 20 },
    { level: 146, weight: 12 },
  ]}
  align="right"
/>
```

## Edge cases

```tsx
// identical levels collapse into a single bin — the summary refuses to
// claim a concentration and reads "Activity is evenly spread."
<VolumeProfile data={[142, 142, 142, 142]} />
```

```tsx
// no data → no marks, and the accessible name is "No data."
<VolumeProfile data={[]} />
```


## Why this default

A perpendicular histogram because "where" is a different question from "when", and no time-axis chart can answer it. The
value area is a stated convention — `valueArea` defaults to `0.7`, and the fraction is stated in the summary — not an
implied confidence interval. The modal bin is the only accented mark, because "where did activity pile up" is the one
question the shape is built to answer.

## Accessibility

The accessible name states where activity concentrates — **"Activity concentrates at 142.33 (POC); 70% within
140.33–145.67."** (the right-aligned demo's 5-level profile, default 12 bins). An even distribution reads **"Activity is
evenly spread."** The interactive entry roves the levels with ↑/↓, announcing each level's share of activity and
flagging the POC.

The interactive entry follows the shared [interaction contract](/docs/accessibility#one-interaction-contract):
arrow keys rove between units on both axes, `Home` and `End` jump to the ends, and a click, tap, `Enter` or
`Space` selects a unit — pinning its readout so it survives blur, until you select it again or press `Escape`.
On touch, a tap pins and a drag scrubs.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `data` (required) | `{ level, weight }[] \| number[]` | Activity mass per level, or raw levels. |
| `valueArea` | `number` | Mass fraction of the shaded value area (0.7). |
| `align` | `"left" \| "right"` | Which way bars grow. |
| `label` | `"poc" \| "none"` | The POC level beside the accent bar. |
| `bins` | `number` | Number of histogram bins (default 12). |
| `animate` | `boolean` | (interactive) Opt-in entrance motion when the chart mounts client-side — add `import "@microcharts/react/motion"` once. Inert on the server, on hydrated server HTML, and under `prefers-reduced-motion`. |

Plus the shared grammar — `data`, `domain`, `color`, `title`, `summary`, `format` — and the layout props (`width`, `height`, `className`, `style`) that every chart accepts. Interactive entries also share `animate` and `live`, and — wherever a chart has more than one navigable unit — `onActive`, `onSelect`, `selectedIndex` and `defaultSelectedIndex`; and — wherever the chart shows a hover value — `readout`. See [the shared grammar](/docs/quickstart#the-shared-grammar).