# natui entrypoint

> Reference run, RunOptions, NatuiApp, components, protocol types, and advanced exports.

Canonical: https://natui.dev/docs/api/natui

The primary entrypoint exports every component plus the Node-driven runtime.

## run [#run]

```ts
function run(
  element: ReactNode,
  options?: RunOptions,
): Promise<NatuiApp>
```

Starts the host, validates its platform and protocol handshake, sends window properties, and mounts the React element.

## RunOptions [#runoptions]

`RunOptions` includes optional `title`, `width`, `height`, `minWidth`, and `minHeight`, plus:

### RunOptions


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `host` | `string \| HostCommand \| undefined` | No | Host binary override; defaults to NATUI_HOST env or the in-repo build. |
| `onClose` | `(() => void) \| undefined` | No | Called when the user closes the window. Default: unmount and exit. |
| `readyTimeoutMs` | `number \| undefined` | No | Startup handshake timeout override (mainly for tests). |
| `title` | `string \| undefined` | No |  |
| `width` | `number \| undefined` | No |  |
| `height` | `number \| undefined` | No |  |
| `minWidth` | `number \| undefined` | No |  |
| `minHeight` | `number \| undefined` | No |  |

| Property         | Purpose                                             |
| ---------------- | --------------------------------------------------- |
| `host`           | Host executable string or `{ cmd, args? }` override |
| `onClose`        | Callback for native window close                    |
| `readyTimeoutMs` | Startup handshake timeout override                  |

Without `onClose`, closing the native window unmounts React, sends `quit`, and exits the Node process.

## NatuiApp [#natuiapp]

### NatuiApp


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `dump` | `() => Promise<TreeNode>` | Yes | Debug: ask the host for its current native tree. |
| `screenshot` | `(path: string) => Promise<string>` | Yes | Debug: host renders its window content to a PNG at `path`. |
| `emit` | `(id: number, name: string, payload?: Record<string, unknown>) => void` | Yes | Debug: make the host synthesize a user event on node `id`. |
| `edit` | `(id: number, value: unknown) => void` | Yes | Debug: make the host perform a real optimistic user edit on node `id` (same code path as typing/dragging: local write, seq, change event). |
| `update` | `(element: ReactNode) => void` | Yes | Re-render with a new element (e.g. for external hot reload). |
| `quit` | `() => void` | Yes | Unmount, quit the host, close the transport. |

| Method                     | Result                                                |
| -------------------------- | ----------------------------------------------------- |
| `dump()`                   | Resolves to the current native `TreeNode`             |
| `screenshot(path)`         | Resolves to the written PNG path                      |
| `emit(id, name, payload?)` | Synthesizes a debug event                             |
| `edit(id, value)`          | Performs an optimistic debug edit                     |
| `update(element)`          | Renders a new React element                           |
| `quit()`                   | Unmounts, asks the host to quit, and closes transport |

## Other exports [#other-exports]

The entrypoint re-exports all components, protocol types, `PROTOCOL_VERSION`, `ROOT_ID`, `Bridge`, `createNatuiRenderer`, `spawnStdioTransport`, `Transport`, `HostCommand`, and `defaultHostCommand`.