# definePrimitive

```ts
import { definePrimitive } from "@pibbl/core";
```

`definePrimitive(render, capabilities?)` creates a Pibbl primitive component from a [`PrimitiveRender`](/reference/types/styles/#primitiverender) callback and optional [`PrimitiveCapabilities`](/reference/types/styles/#primitivecapabilities),
with private style normalization, resolution, and optional measurement
capabilities. Use it for component-library primitives, not ordinary application
components: invoking its returned component outside the Pibbl renderer throws.

```ts
const Dot = definePrimitive(function renderDot(props) {
  // paint with the active Pibbl Canvas context
});
```

The exact generic contracts are in the Elements and components type reference;
primitive painting receives Pibbl's active [`Canvas`](/reference/types/canvas-runtime/#canvas) context.
See [Custom components and primitives](/guides/custom-components-and-primitives/).

## API details from source

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

Defines a platform component with private style and measurement behavior.

```ts
definePrimitive: <P = Record<string, never>, S extends SystemStyle = SystemStyle, N extends SystemStyle = S, R extends SystemStyle = N>(render: PrimitiveRender<P, R> & PrimitiveStyleGuard<S, N, R> & (PrimitiveInput<P, S> extends never ? never : unknown), ...capabilityArguments: CapabilityArguments<P, S, N, R>) => PibblPrimitiveComponent<PrimitiveProgramProps<P>, PrimitiveInput<P, S>>
```

Related API: [definePrimitive](/reference/functions/define-primitive/), [SystemStyle](/reference/types/styles/#systemstyle), [PrimitiveRender](/reference/types/styles/#primitiverender), [PrimitiveInput](/reference/types/styles/#primitiveinput), [PibblPrimitiveComponent](/reference/types/elements-components/#pibblprimitivecomponent), [PrimitiveProgramProps](/reference/types/styles/#primitiveprogramprops).

### Parameters

- **`render`** — Synchronous primitive renderer receiving props, resolved style, and Canvas
context. See [PrimitiveRender](/reference/types/styles/#primitiverender) , `PrimitiveStyleGuard` , [PrimitiveInput](/reference/types/styles/#primitiveinput) .

- **`capabilityArguments`** — Style normalization, resolution, and measurement capabilities
required by the primitive. See `CapabilityArguments` .

### Returns

A primitive component usable with JSX or createElement. See
[PibblPrimitiveComponent](/reference/types/elements-components/#pibblprimitivecomponent) , [PrimitiveProgramProps](/reference/types/styles/#primitiveprogramprops) , [PrimitiveInput](/reference/types/styles/#primitiveinput) .

### See also

[PrimitiveRender](/reference/types/styles/#primitiverender)

[PrimitiveInput](/reference/types/styles/#primitiveinput)

[PibblPrimitiveComponent](/reference/types/elements-components/#pibblprimitivecomponent)

[PrimitiveProgramProps](/reference/types/styles/#primitiveprogramprops)

[SystemStyle](/reference/types/styles/#systemstyle)

[View source — packages/core/src/lib/define-primitive.ts:83](/source/packages/core/src/lib/define-primitive-ts/#L83)

## Implementation guidance for agents

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

## Complete minimal examples

- [Define a Canvas primitive](/minimal-examples/lifecycle/primitive/): Supply synchronous drawing, style normalization, resolution, and opt-in measurement. [Plain source](/minimal/lifecycle/primitive.tsx)
## Interactive examples

- [Energy Transitions](/examples/energy-transitions/) · [Full page](/experience/energy-transitions/)
## Documentation version

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