# measureElement

```ts
import {
  createElement,
  measureElement,
  Rectangle,
  type CanvasMeasurementService,
  type Constraints,
} from "@pibbl/core";
```

`measureElement(element, constraints, service)` measures one element through
its opt-in primitive capability. It is pure: it cannot render or acquire
runtime resources. Components without a measure capability return an
`unsupported` result, and cyclic measurement dependencies are rejected.

Signal writes are rejected throughout measurement, including custom normalization,
measurement callbacks and the text-measurement service. This also applies when
called outside a mounted component. A rejected signal update does not run its
updater or change its value; ordinary writes remain available after measurement
returns or throws.

```ts
const element = createElement(Rectangle, {
  style: { width: 120, height: 60, fill: "#2563eb" },
});
const constraints: Constraints = {
  minWidth: 0,
  maxWidth: 240,
  minHeight: 0,
  maxHeight: 120,
};
const measurementService: CanvasMeasurementService = {
  measureText: () => ({}) as TextMetrics,
};
const result = measureElement(element, constraints, measurementService);
```

[`Constraints`](/reference/types/layout/#constraints) and a [`CanvasMeasurementService`](/reference/types/layout/#canvasmeasurementservice) describe the call; its result is a [`MeasureResult`](/reference/types/layout/#measureresult). Use declared boxes for ordinary layout rather than assuming visual primitives
have intrinsic dimensions.

## API details from source

<span id="api-measureElement"></span>

Measures an element against finite constraints using the supplied Canvas measurement service.

```ts
measureElement: (element: PibblElement<any>, constraints: Readonly<Constraints>, service: CanvasMeasurementService) => MeasureResult
```

Related API: [measureElement](/reference/functions/measure-element/), [PibblElement](/reference/types/elements-components/#pibblelement), [Constraints](/reference/types/layout/#constraints), [CanvasMeasurementService](/reference/types/layout/#canvasmeasurementservice), [MeasureResult](/reference/types/layout/#measureresult).

### Parameters

- **`element`** — Element whose declared measurement capability is used. See [PibblElement](/reference/types/elements-components/#pibblelement).

- **`constraints`** — Available size constraints in logical units. See [Constraints](/reference/types/layout/#constraints).

- **`service`** — Canvas text measurement service. See [CanvasMeasurementService](/reference/types/layout/#canvasmeasurementservice).

### Returns

Measured dimensions, or an unsupported result with its reason. See
[MeasureResult](/reference/types/layout/#measureresult) .

### See also

[PibblElement](/reference/types/elements-components/#pibblelement)

[Constraints](/reference/types/layout/#constraints)

[CanvasMeasurementService](/reference/types/layout/#canvasmeasurementservice)

[MeasureResult](/reference/types/layout/#measureresult)

[View source — packages/core/src/lib/layout/measure.ts:46](/source/packages/core/src/lib/layout/measure-ts/#L46)

## Implementation guidance for agents

Read the [Drawing, layout, and effects companion](/agents/topics/layout/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Intrinsic measurement](/minimal-examples/layout/measure/): Measure a Text element with a Canvas service and display its computed dimensions. [Plain source](/minimal/layout/measure.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.