# HtmlBox

`HtmlBox` allocates a native HTML DIV above the canvas. Pibbl owns its placement,
affine transforms, inherited `PathGeometry` clips, and mounted identity. The
browser owns its content, editing, semantics, and native events.

```tsx
import { HtmlBox } from "@pibbl/core";

<HtmlBox
  data="Name"
  style={{ width: 240, height: 80 }}
  mount={(element, label, signal) => {
    const input = document.createElement("input");
    input.setAttribute("aria-label", label);
    element.append(input);
    input.addEventListener("input", () => console.log(input.value), { signal });
    return (nextLabel) => input.setAttribute("aria-label", nextLabel);
  }}
/>;
```

Mount runs once after attaching the DIV. The returned function receives subsequent
rendered data; the initial data is not delivered twice. The supplied AbortSignal
aborts once before removal, including mount/update failure. Use an abort listener
to disconnect observers or unmount an embedded framework. Mount and update must
be synchronous. Native input handlers can write Pibbl signals; lifecycle callbacks
cannot.

Configure the initial `pibbl` call with `htmlOverlay`, an empty HTML sibling
immediately after the canvas inside a shared positioned wrapper. Both must occupy
the same content rectangle with no border, padding, or independent CSS transform.
Apply page transforms to the wrapper. The runtime does not reparent the canvas.
See the [copyable HTML Box example](/playground/#/examples/composition/html-box) for setup and
cleanup.

`style` accepts Pibbl box sizing, padding, layout participation, Group transforms,
opacity, and overflow (default `clip`). HTML does not determine Pibbl intrinsic
sizes. `pointerEvents="none"` disables the host's pointer and focus participation.
A changed `key` replaces the mounted content; an inline mount callback changing
identity does not.

With `FocusManagement`, native controls enter the source-order navigation between
Canvas targets. Native text editing and activation stay native. Without it, the
browser's DOM order applies. Use ordinary descendant `.focus()` for programmatic
focus and `onFocusChange` for region focus-within state.

HTML stays above all Canvas paint. Canvas filters and non-default compositing
cannot enclose HTML. Native `Path2D` ancestor clips must be replaced by
`PathGeometry`; curves and fill rules retain their geometry, with browser-specific
edge antialiasing. Clipping does not remove controls from keyboard navigation.
Managed focus initially supports ordinary light DOM with nonpositive tabindex;
shadow/iframe internals and top-layer portals are outside that guarantee. Canvas
screenshots do not include HTML. Keyed reorder preserves nodes but does not reorder
native accessibility reading order.

Type reference: [HtmlBoxProps](/reference/types/html-box/#htmlboxprops),
[HtmlBoxStyle](/reference/types/html-box/#htmlboxstyle),
[HtmlMountCallback](/reference/types/html-box/#htmlmountcallback),
[HtmlUpdateFunction](/reference/types/html-box/#htmlupdatefunction), and
[HtmlBoxFocusState](/reference/types/html-box/#htmlboxfocusstate).

## API details from source

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

A persistent native HTML box projected into Pibbl layout, transforms and clips.

```ts
HtmlBox: HtmlBoxComponent
```

Related API: [HtmlBox](/reference/components/html-box/).

### See also

[HtmlBoxProps](/reference/types/html-box/#htmlboxprops)

[HtmlBoxStyle](/reference/types/html-box/#htmlboxstyle)

[HtmlMountCallback](/reference/types/html-box/#htmlmountcallback)

[View source — packages/core/src/lib/components/html-box.ts:63](/source/packages/core/src/lib/components/html-box-ts/#L63)

## Implementation guidance for agents

Read the [Input, focus, and native HTML companion](/agents/topics/input/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Host a native button in Pibbl](/minimal-examples/lifecycle/html/): Mount and update native HTML inside an HtmlBox, preserving native clicks and focus. [Plain source](/minimal/lifecycle/html.tsx)
## Interactive examples

- [Text envelope playground](/examples/text-envelope/) · [Full page](/experience/text-envelope/)
## Documentation version

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