UI Kit

About Nuwa UI Kit

@nuwa-ai/ui-kit provides a NuwaClient class and a set of React hooks to help you build interactive UI for your Cap.

Example

import { NuwaProvider, useNuwa } from '@nuwa-ai/ui-kit';

function MyCapUI() {
  const { nuwa, connected } = useNuwa();
  return <button onClick={() => nuwa.sendPrompt('Analyze selections')} disabled={!connected}>Run</button>;
}

export default () => (
  <NuwaProvider autoHeight debug>
    <MyCapUI />
  </NuwaProvider>
);

Install

pnpm add @nuwa-ai/ui-kit

NuwaClient

NuwaClient is the main class that you can use to interact with the Nuwa Client. It provides a set of methods that you can use to interact with the Nuwa Client.

You can initialize a NuwaClient instance directly, or use the useNuwa hook to get a NuwaClient instance.

constructor

Create a NuwaClient for parent iframe communication.

const nuwaClient = new NuwaClient(options); // initialize a NuwaClient instance

nuwaClient.connect(); // connect to the Nuwa Client

Inputs

Construct-time options

options · object?

Show options

allowedOrigins · string[]? · default: "[*]"

timeout · number? · default: "2000"

Connection timeout

debug · boolean?

methodTimeout(s) · number? | record?

Per-call overrides

methodRetries(map) · number? | record?

Retry overrides

streamTimeout · number? · default: "30000"

streamRetries · number? · default: "0"

Returns

client · NuwaClient

Configured client instance

sendPrompt

Send a message to the parent client chat.

Inputs

prompt · string · required

Text message to send

Returns

result · Promise<void>

Resolves when sent

setHeight

Set the UI iframe height in the Nuwa Client.

Inputs

height · string | number · required

CSS size or number

Returns

result · Promise<void>

Resolves when applied

addSelection

Add a selection (label + message) to parent UI. Inputs

label · string · required

Selection title. This will be displayed as a badge in the user’s input.

message · string | object · required

Payload message. This will be provided to the AI as part of the system prompt.

Returns

result · Promise<void>

Resolves when added

saveState

Save state to the Nuwa Client.

Inputs

state · any

State to save

Returns

result · Promise<void>

Resolves when applied

getState

Retrieve the state from the Nuwa Client.

Inputs

state · any?

Retrieve the state

Returns

result · Promise<any>

Resolves when applied

createAIStream

Start a LLM stream controlled by nuwa client.

Inputs

Streaming request

request · object · required

Show request

prompt · string · required

Prompt to stream

Returns

handle · StreamHandle

Control/observe the stream

StreamHandle.execute / abort

Run the stream and observe live chunks/errors.

Inputs

Optional callbacks

options · object?

Show options

onChunk · function?

Receive live content/error frames

onError · function?

Receive immediate error

Returns

execute · Promise

Final stream result and error (object with result and error)

abort · void

Cancel the stream

React Helpers

NuwaProvider

Wrap your app and auto-manage connection and resizing.

Inputs

Provider properties

props · object

Show props

autoHeight · boolean? · default: "true"

allowedOrigins · string[]?

timeout · number?

debug · boolean?

methodTimeout(s)/Retries(map) · number? | record?

Overrides

streamTimeout/streamRetries · number?

Streaming

onConnected · function?

onError · function?

className/style · string | object?

Returns

element · ReactElement

Rendered provider element

useNuwa

Access the client, theme, and connection status.

Inputs

(none) · void

Hook takes no parameters

Returns

nuwa · NuwaClient

Client instance

theme · "light"|"dark"

Current theme

connected · boolean

Connection state

MCP Transport

PostMessageMCPTransport (constructor)

A Transport for official MCP SDK over postMessage.

Inputs

Constructor options

options · object?

Show options

targetWindow · Window?

targetOrigin · string? · default: "*"

allowedOrigins · string[]? · default: "[*]"

timeout · number? · default: "30000"

debug · boolean?

securityPolicy · object?

Fields: enforceOriginValidation?, maxMessageSize?, rateLimits?

Returns

transport · PostMessageMCPTransport

Configured transport

start / send / connect / disconnect

Transport lifecycle and messaging.

Inputs

(varies) · -

See individual methods

Returns

start · Promise<void>

Begin listening

send · Promise<void>

Send JSON-RPC message

connect · Promise<void>

Connect to window

disconnect · void

Tear down transport

connected/ready · boolean

Current status flags

UI Helpers

Return UI resources from MCP tools.

Inputs

path · string · required

Path relative to artifact origin

name/description/uiType · string?

Optional metadata

Returns

resource · UIResource

Result for createUIResource

toolResult · UIToolResult

Result for createUIToolResult