# `Overlays.dimensions`

> Contract 2.0.0 · package sha256 `a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e` · generated from `configurator-runtime.d.ts` by `services/onsite-scripter/scripts/build-contract-docs.mjs`; edit the source, not this file.

Method of [`Overlays`](Overlays.md) · stable · since 2.0.0 · called as `session.overlays.dimensions`

```ts
dimensions(query: Query | null, options?: DimensionOptions): void;
```

Rulers for the matched parts' bounds; null hides them. Derived from current bounds, never last-rendered. Each label sits at the projected middle of its dimension line; one whose middle projects outside the view, or within half its own size of the edge (so part of it would leave the view), is drawn flush inside that edge, and one wider or taller than the view is centred on it. Sync; drawn from the next frame, or, before the ruler code has loaded (at idle after the first complete frame), from the first frame after it loads (spec section 6.3).

## Options

Through [`Session`](Session.md):

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `axes` | `ReadonlyArray<'width' \| 'height' \| 'depth'>` | ['width', 'height', 'depth'] | The rulers drawn: 'width' measures the bounds' world X extent, 'height' Y and 'depth' Z. |
| `format` | `DimensionFormat \| ((metres: number, axis: 'width' \| 'height' \| 'depth') => string)` | { unit: 'cm', decimals: 0 } | A format, or a function from metres to label text. |
| `per` | `'all' \| 'part' \| 'node'` | 'all' | 'part': one ruler set per matched part. |

## Generic-API test (spec 3.1)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `dimensions` names no product |
| 2. A precedent | pass: [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) (row `G14`); [Unity Renderer.bounds](https://docs.unity3d.com/ScriptReference/Renderer-bounds.html) (row `G14`); [Babylon.js GUI Control.linkWithMesh](https://github.com/BabylonJS/Babylon.js/blob/master/packages/dev/gui/src/2D/controls/control.ts) (row `K48`) |
| 3. Two apps, or labs | pass: 23 apps (ledger: app-4f16d2f6da, app-510d750508, app-b362a81c85, app-bcb7ef21da, app-ceb4eccc72, app-fb16dd1985, app-fc07850558, app-fc306ec3dc and 1 more; fleet cross-check: app-04c2774145, app-37356bf09f, app-4762caacdc, app-4f16d2f6da, app-4fd23bc869, app-510d750508, app-822bb9d6aa, app-8675b3225c and 15 more) |
| 4. The cheaper fix first | decided per need in Appendix B: rows `G14`, `K48` at tier stable (a member only where no rule, data, asset or app code serves the need) |