# Describing your data

Dimensions, measures, field options and the one response shape every chart takes.

The samples assume the `ChartsProvider` from [step 2 of the quick start](/docs/quick-start.md#2-add-the-provider).

Charts do not guess what your columns mean. You describe each one once, as a **dimension** (something you group by) or a **measure** (a number), and reuse the description in every chart.

## A dimension and a measure

This chart groups by one dimension, the plan, and plots one measure, the recurring revenue.

```tsx title="PlanChart.tsx"
import { BarChart, dimension, measure, results } from 'em-kit';

// A dimension is something you group by.
const plan = dimension({ name: 'plan', title: 'Plan' });

// A measure is a number. Display options go on `inputs`.
const mrr = measure({
  name: 'mrr',
  title: 'Monthly recurring revenue',
  inputs: { currency: 'EUR', abbreviateLargeNumber: true },
});

// Each row has one key per field name.
const rows = [
  { plan: 'Starter', mrr: 84200 },
  { plan: 'Growth', mrr: 213500 },
  { plan: 'Enterprise', mrr: 391000 },
];

export function PlanChart() {
  return (
    <div style={{ height: 320 }}>
      <BarChart
        title="Recurring revenue by plan"
        dimension={plan}
        measures={[mrr]}
        results={results(rows)}
      />
    </div>
  );
}
```

Result: three bars, labelled €84K, €214K and €391K.

## Field properties

| Property | What it is |
|---|---|
| `name` | The key the chart reads from each row. |
| `title` | The label on axes, legends, tooltips and table headers. Defaults to `name`. |
| `type` | `string`, `number`, `time` or `boolean`. Dimensions default to `string` and measures to `number`. |
| `granularity` | Time dimensions only: `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter` or `year`. See below. |
| `inputs` | The field options below. |

Set `granularity` on the dimension itself, at the top level of `dimension()`. It formats the axis (`month` shows `Jan 2026`) and fills missing periods. See [Time series](/docs/time-series.md).

A chart’s own `granularity` prop formats and fills nothing. It says which granularity the rows you pass are at now, so a click handler can turn a clicked period into a time range. Left out, it follows the dimension’s.

## Field options

Field options go in a field’s `inputs` and apply wherever the field is shown: axes, value labels, tooltips, legends and table cells.

| Option | For | What it does |
|---|---|---|
| `prefix` | Any field | Text before each value. `prefix: '$'` shows `$48,200`. |
| `suffix` | Any field | Text after each value. `suffix: '%'` shows `12%`. |
| `decimalPlaces` | Numbers | A fixed number of decimal places. `1` shows `12.5`. |
| `currency` | Numbers | An ISO currency code such as `EUR`. The value is formatted as money in the reader’s locale. |
| `abbreviateLargeNumber` | Numbers | Shortens large numbers: `1,200,000` becomes `1.2M`. |
| `displayName` | Any field | A label shown in place of `title`. |
| `maxCharacters` | Text | Cuts longer text off at this length and adds `...`. |
| `displayNullAs` | Any field | Text shown when a value is missing, such as `n/a`. |
| `showGranularityDropdown` | Time dimensions | Shows a granularity picker in the card. See [Time series](/docs/time-series.md#let-readers-change-the-granularity). |
| `dateBounds` | Time dimensions | `{ from, to }`: the first and last date on the axis. The default is the range of your rows. |
| `ignoreEmptyDate` | Time dimensions | Leaves out periods with no rows instead of showing them as gaps. |
| `color`, `lineColor` | Measures | A colour for this measure’s bars or line. Bar and line charts only. |

There is no date format option: dates follow the granularity and the [provider’s locale](/docs/localisation.md). Options that only one chart reads, such as a dashed line or a pivot total, are listed on that [component’s page](/docs/components.md).

## The response shape

Every component takes its rows through one prop, `results`. `results(rows)` builds it from an array, and counts as loading until `rows` has a value.

| Key | Type | What it is |
|---|---|---|
| `isLoading` | `boolean` | Whether a request is in flight. |
| `data` | Array of objects | Your rows. |
| `error` | `string` | A message to show in place of the chart. |
| `total` | `number` | The total row count, for paginated tables. |

[Loading, empty and errors](/docs/loading-empty-and-errors.md) shows what each combination draws.
