# HTML box types

## HtmlBoxFocusState

Readonly `isFocusWithin` and `isFocusVisible` booleans describe the whole native
region. Native descendants keep their browser focus and focus rings.

See [HtmlBox](/reference/components/html-box/).

## HtmlBoxProps

`data` is the opaque application payload, `mount` is its mount callback,
`pointerEvents` is `"auto" | "none"`, and optional `onFocusChange` observes the
region snapshot. Read a Pibbl signal with `.get()` to subscribe the enclosing
component when replacing data. `data` is not recursively resolved.

## HtmlBoxStyle

Pibbl box/layout fields and Group affine transform fields, plus opacity. Width and
height default to the parent's allocation; DOM content does not define intrinsic
size. Overflow defaults to clip. Canvas filters enclosing HtmlBox are unsupported.

## HtmlMountCallback

```ts
type HtmlMountCallback<Props> = (
  element: HTMLDivElement,
  initialProps: Props,
  signal: AbortSignal,
) => HtmlUpdateFunction<Props>;
```

Creates content once in a connected DIV and returns its updater. Use the native
AbortSignal for listener and resource cleanup before the DIV is removed.

## HtmlUpdateFunction

```ts
type HtmlUpdateFunction<Props> = (props: Props) => void;
```

Updates persistent content after subsequent successful component renders. A clean
Layer reprojection does not call the updater. Return a no-op if updates are unused.

## API details from source

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

### HtmlBoxProps

Props for a DOM-hosting region, including mount ownership, updates, and focus behavior.

```ts
interface HtmlBoxProps<Props>
```

Related API: [HtmlBoxProps](/reference/types/html-box/#htmlboxprops).

#### See also

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

[HtmlBoxFocusState](/reference/types/html-box/#htmlboxfocusstate)

[HtmlBox](/reference/components/html-box/)

[View source — packages/core/src/lib/html/types.ts:51](/source/packages/core/src/lib/html/types-ts/#L51)

#### Properties and methods

<span id="api-HtmlBoxProps-data"></span>
<details>
<summary>data</summary>


```ts
data: Props
```

Application data supplied to the component or reported by the event. See HtmlBoxProps
.

[View source — packages/core/src/lib/html/types.ts:56](/source/packages/core/src/lib/html/types-ts/#L56)

</details>

<span id="api-HtmlBoxProps-mount"></span>
<details>
<summary>mount</summary>


```ts
mount: HtmlMountCallback<Props>
```

Related API: [HtmlMountCallback](/reference/types/html-box/#htmlmountcallback).

Creates mounted content and its owned lifecycle controls. See HtmlMountCallback.

[View source — packages/core/src/lib/html/types.ts:58](/source/packages/core/src/lib/html/types-ts/#L58)

</details>

<span id="api-HtmlBoxProps-pointerEvents"></span>
<details>
<summary>pointerEvents (optional)</summary>


```ts
pointerEvents?: "auto" | "none" | undefined
```

Whether this content participates in pointer targeting. See HtmlBoxProps.

[View source — packages/core/src/lib/html/types.ts:60](/source/packages/core/src/lib/html/types-ts/#L60)

</details>

<span id="api-HtmlBoxProps-onFocusChange"></span>
<details>
<summary>onFocusChange (optional)</summary>


```ts
onFocusChange?: ((state: Readonly<HtmlBoxFocusState>) => void) | undefined
```

Related API: [HtmlBoxFocusState](/reference/types/html-box/#htmlboxfocusstate).

Receives changes to focus within the hosted HTML region. See HtmlBoxFocusState.

##### Parameters

- **`state`** — Current DOM and Pibbl focus ownership for the HTML region. See
[HtmlBoxFocusState](/reference/types/html-box/#htmlboxfocusstate) .

[View source — packages/core/src/lib/html/types.ts:66](/source/packages/core/src/lib/html/types-ts/#L66)

</details>

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

### HtmlBoxStyle

Layout and presentation of an application-owned HTML region anchored to Canvas geometry.

```ts
interface HtmlBoxStyle extends GStyle
```

Related API: [HtmlBoxStyle](/reference/types/html-box/#htmlboxstyle), [GStyle](/reference/types/styles/#gstyle).

#### See also

[GStyle](/reference/types/styles/#gstyle)

[HtmlBox](/reference/components/html-box/)

[View source — packages/core/src/lib/html/types.ts:74](/source/packages/core/src/lib/html/types-ts/#L74)

#### Properties and methods

<span id="api-HtmlBoxStyle-height"></span>
<details>
<summary>height (optional)</summary>


```ts
height?: Length | undefined
```

Related API: [Length](/reference/types/layout/#length).

Vertical extent in the units of the containing geometry or surface. See Length.

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

</details>

<span id="api-HtmlBoxStyle-minWidth"></span>
<details>
<summary>minWidth (optional)</summary>


```ts
minWidth?: number | `${number}%` | undefined
```

Minimum permitted width. See Length.

[View source — packages/core/src/lib/style/types.ts:85](/source/packages/core/src/lib/style/types-ts/#L85)

</details>

<span id="api-HtmlBoxStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).

Opacity of the painted result. See HtmlBoxStyle.

[View source — packages/core/src/lib/html/types.ts:76](/source/packages/core/src/lib/html/types-ts/#L76)

</details>

<span id="api-HtmlBoxStyle-transition"></span>
<details>
<summary>transition (optional)</summary>


```ts
transition?: PibblTransitionBinding | undefined
```

Related API: [PibblTransitionBinding](/reference/hooks/use-visibility-transition/).

Visibility-transition binding applied to this primitive and its captured descendants. See SystemStyle.

[View source — packages/core/src/lib/types.ts:69](/source/packages/core/src/lib/types-ts/#L69)

</details>

<span id="api-HtmlBoxStyle-left"></span>
<details>
<summary>left (optional)</summary>


```ts
left?: number | `${number}%` | undefined
```

Left edge coordinate or inset. See Length.

[View source — packages/core/src/lib/style/positioning.ts:127](/source/packages/core/src/lib/style/positioning-ts/#L127)

</details>

<span id="api-HtmlBoxStyle-top"></span>
<details>
<summary>top (optional)</summary>


```ts
top?: number | `${number}%` | undefined
```

Top edge value or top envelope guide. See Length.

[View source — packages/core/src/lib/style/positioning.ts:129](/source/packages/core/src/lib/style/positioning-ts/#L129)

</details>

<span id="api-HtmlBoxStyle-width"></span>
<details>
<summary>width (optional)</summary>


```ts
width?: Length | undefined
```

Related API: [Length](/reference/types/layout/#length).

Horizontal extent in the units of the containing geometry or surface. See Length.

[View source — packages/core/src/lib/style/types.ts:81](/source/packages/core/src/lib/style/types-ts/#L81)

</details>

<span id="api-HtmlBoxStyle-maxWidth"></span>
<details>
<summary>maxWidth (optional)</summary>


```ts
maxWidth?: number | `${number}%` | undefined
```

Maximum permitted width. See Length.

[View source — packages/core/src/lib/style/types.ts:87](/source/packages/core/src/lib/style/types-ts/#L87)

</details>

<span id="api-HtmlBoxStyle-minHeight"></span>
<details>
<summary>minHeight (optional)</summary>


```ts
minHeight?: number | `${number}%` | undefined
```

Minimum permitted height. See Length.

[View source — packages/core/src/lib/style/types.ts:89](/source/packages/core/src/lib/style/types-ts/#L89)

</details>

<span id="api-HtmlBoxStyle-maxHeight"></span>
<details>
<summary>maxHeight (optional)</summary>


```ts
maxHeight?: number | `${number}%` | undefined
```

Maximum permitted height. See Length.

[View source — packages/core/src/lib/style/types.ts:91](/source/packages/core/src/lib/style/types-ts/#L91)

</details>

<span id="api-HtmlBoxStyle-padding"></span>
<details>
<summary>padding (optional)</summary>


```ts
padding?: EdgeValues | undefined
```

Related API: [EdgeValues](/reference/types/layout/#edgevalues).

Insets between the border box and content box. See EdgeValues.

[View source — packages/core/src/lib/style/types.ts:93](/source/packages/core/src/lib/style/types-ts/#L93)

</details>

<span id="api-HtmlBoxStyle-overflow"></span>
<details>
<summary>overflow (optional)</summary>


```ts
overflow?: "clip" | "visible" | undefined
```

Selects `"visible"`, `"clip"` for overflow. See BoxStyle.

[View source — packages/core/src/lib/style/types.ts:95](/source/packages/core/src/lib/style/types-ts/#L95)

</details>

<span id="api-HtmlBoxStyle-alignSelf"></span>
<details>
<summary>alignSelf (optional)</summary>


```ts
alignSelf?: "auto" | "center" | "end" | "flex-end" | "flex-start" | "start" | "stretch" | undefined
```

This child's cross-axis or block-axis alignment override. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:121](/source/packages/core/src/lib/style/types-ts/#L121)

</details>

<span id="api-HtmlBoxStyle-justifySelf"></span>
<details>
<summary>justifySelf (optional)</summary>


```ts
justifySelf?: "auto" | "center" | "end" | "start" | "stretch" | undefined
```

This child's inline-axis alignment override. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:123](/source/packages/core/src/lib/style/types-ts/#L123)

</details>

<span id="api-HtmlBoxStyle-flexBasis"></span>
<details>
<summary>flexBasis (optional)</summary>


```ts
flexBasis?: Length | undefined
```

Related API: [Length](/reference/types/layout/#length).

Initial main-axis size before flex growth or shrinkage. See Length.

[View source — packages/core/src/lib/style/types.ts:125](/source/packages/core/src/lib/style/types-ts/#L125)

</details>

<span id="api-HtmlBoxStyle-flexGrow"></span>
<details>
<summary>flexGrow (optional)</summary>


```ts
flexGrow?: number | undefined
```

Relative share of positive free space assigned to this child. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:127](/source/packages/core/src/lib/style/types-ts/#L127)

</details>

<span id="api-HtmlBoxStyle-flexShrink"></span>
<details>
<summary>flexShrink (optional)</summary>


```ts
flexShrink?: number | undefined
```

Relative factor used when reducing main-axis size. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:129](/source/packages/core/src/lib/style/types-ts/#L129)

</details>

<span id="api-HtmlBoxStyle-gridColumnStart"></span>
<details>
<summary>gridColumnStart (optional)</summary>


```ts
gridColumnStart?: number | undefined
```

Explicit starting grid column. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:131](/source/packages/core/src/lib/style/types-ts/#L131)

</details>

<span id="api-HtmlBoxStyle-gridColumnSpan"></span>
<details>
<summary>gridColumnSpan (optional)</summary>


```ts
gridColumnSpan?: number | undefined
```

Number of columns occupied by this child. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:133](/source/packages/core/src/lib/style/types-ts/#L133)

</details>

<span id="api-HtmlBoxStyle-gridRowStart"></span>
<details>
<summary>gridRowStart (optional)</summary>


```ts
gridRowStart?: number | undefined
```

Explicit starting grid row. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:135](/source/packages/core/src/lib/style/types-ts/#L135)

</details>

<span id="api-HtmlBoxStyle-gridRowSpan"></span>
<details>
<summary>gridRowSpan (optional)</summary>


```ts
gridRowSpan?: number | undefined
```

Number of rows occupied by this child. See LayoutItemStyle.

[View source — packages/core/src/lib/style/types.ts:137](/source/packages/core/src/lib/style/types-ts/#L137)

</details>

<span id="api-HtmlBoxStyle-scaleX"></span>
<details>
<summary>scaleX (optional)</summary>


```ts
scaleX?: number | undefined
```

Horizontal scale factor. See GStyle.

[View source — packages/core/src/lib/components/g.ts:45](/source/packages/core/src/lib/components/g-ts/#L45)

</details>

<span id="api-HtmlBoxStyle-scaleY"></span>
<details>
<summary>scaleY (optional)</summary>


```ts
scaleY?: number | undefined
```

Vertical scale factor. See GStyle.

[View source — packages/core/src/lib/components/g.ts:47](/source/packages/core/src/lib/components/g-ts/#L47)

</details>

<span id="api-HtmlBoxStyle-rotationDegrees"></span>
<details>
<summary>rotationDegrees (optional)</summary>


```ts
rotationDegrees?: number | undefined
```

Clockwise rotation in degrees.

[View source — packages/core/src/lib/components/g.ts:49](/source/packages/core/src/lib/components/g-ts/#L49)

</details>

<span id="api-HtmlBoxStyle-rotationOrigin"></span>
<details>
<summary>rotationOrigin (optional)</summary>


```ts
rotationOrigin?: [number, number] | undefined
```

Point around which the rotation is applied. See GStyle.

[View source — packages/core/src/lib/components/g.ts:51](/source/packages/core/src/lib/components/g-ts/#L51)

</details>

<span id="api-HtmlBoxStyle-translateX"></span>
<details>
<summary>translateX (optional)</summary>


```ts
translateX?: number | undefined
```

Horizontal translation in the current logical coordinate system. See GStyle.

[View source — packages/core/src/lib/components/g.ts:53](/source/packages/core/src/lib/components/g-ts/#L53)

</details>

<span id="api-HtmlBoxStyle-translateY"></span>
<details>
<summary>translateY (optional)</summary>


```ts
translateY?: number | undefined
```

Vertical translation in the current logical coordinate system. See GStyle.

[View source — packages/core/src/lib/components/g.ts:55](/source/packages/core/src/lib/components/g-ts/#L55)

</details>

<span id="api-HtmlBoxStyle-skewX"></span>
<details>
<summary>skewX (optional)</summary>


```ts
skewX?: number | undefined
```

Horizontal skew angle in degrees.

[View source — packages/core/src/lib/components/g.ts:57](/source/packages/core/src/lib/components/g-ts/#L57)

</details>

<span id="api-HtmlBoxStyle-skewY"></span>
<details>
<summary>skewY (optional)</summary>


```ts
skewY?: number | undefined
```

Vertical skew angle in degrees.

[View source — packages/core/src/lib/components/g.ts:59](/source/packages/core/src/lib/components/g-ts/#L59)

</details>

<span id="api-HtmlBoxStyle-custom"></span>
<details>
<summary>custom (optional)</summary>


```ts
custom?: unknown
```

Application-defined style payload passed through the runtime. See SystemStyle.

[View source — packages/core/src/lib/types.ts:71](/source/packages/core/src/lib/types-ts/#L71)

</details>

<span id="api-HtmlBoxStyle-filter"></span>
<details>
<summary>filter (optional)</summary>


```ts
filter?: PibblFilter | readonly PibblFilter[] | undefined
```

Related API: [PibblFilter](/reference/types/filters/#pibblfilter).

Ordered pixel-only filters applied to the receiving primitive and its descendants. See
PibblFilter.

[View source — packages/core/src/lib/types.ts:76](/source/packages/core/src/lib/types-ts/#L76)

</details>

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

### HtmlMountCallback

Mounts application HTML into the supplied host and returns its prop-update callback; the abort
signal marks teardown.

```ts
type HtmlMountCallback<Props> = (element: HTMLDivElement, initialProps: Props, signal: AbortSignal) => HtmlUpdateFunction<Props>
```

Related API: [HtmlMountCallback](/reference/types/html-box/#htmlmountcallback), [signal](/reference/functions/signal/), [HtmlUpdateFunction](/reference/types/html-box/#htmlupdatefunction).

#### Parameters

- **`element`** — Pibbl-owned host div into which application content may be mounted.

- **`initialProps`** — Props from the initial mount.

- **`signal`** — Lifetime signal aborted when the host is disposed.

#### Returns

An update callback for subsequent props; release application resources when the signal
aborts. See [HtmlUpdateFunction](/reference/types/html-box/#htmlupdatefunction) .

#### See also

[HtmlUpdateFunction](/reference/types/html-box/#htmlupdatefunction)

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

[HtmlBox](/reference/components/html-box/)

[View source — packages/core/src/lib/html/types.ts:29](/source/packages/core/src/lib/html/types-ts/#L29)

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

### HtmlUpdateFunction

Updates mounted application HTML when the owning HtmlBox receives new props.

```ts
type HtmlUpdateFunction<Props> = (props: Props) => void
```

Related API: [HtmlUpdateFunction](/reference/types/html-box/#htmlupdatefunction).

#### Parameters

- **`props`** — Latest props for the mounted HTML content.

#### See also

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

[View source — packages/core/src/lib/html/types.ts:14](/source/packages/core/src/lib/html/types-ts/#L14)

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

### HtmlBoxFocusState

Focus state shared between an HTML host and Pibbl's logical focus management.

```ts
interface HtmlBoxFocusState
```

Related API: [HtmlBoxFocusState](/reference/types/html-box/#htmlboxfocusstate).

#### See also

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

[View source — packages/core/src/lib/html/types.ts:35](/source/packages/core/src/lib/html/types-ts/#L35)

#### Properties and methods

<span id="api-HtmlBoxFocusState-isFocusWithin"></span>
<details>
<summary>isFocusWithin</summary>


```ts
readonly isFocusWithin: boolean
```

Whether an element inside the hosted HTML region currently has focus. See
HtmlBoxFocusState.

[View source — packages/core/src/lib/html/types.ts:40](/source/packages/core/src/lib/html/types-ts/#L40)

</details>

<span id="api-HtmlBoxFocusState-isFocusVisible"></span>
<details>
<summary>isFocusVisible</summary>


```ts
readonly isFocusVisible: boolean
```

Whether focus should be presented as keyboard-visible. See HtmlBoxFocusState.

[View source — packages/core/src/lib/html/types.ts:42](/source/packages/core/src/lib/html/types-ts/#L42)

</details>

## 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)
## Documentation version

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