OpenAI ChatKit

https://openai.github.io/chatkit-js
Admin
OpenAI ChatKit is a framework for building high-quality, AI-powered chat experiences with deep UI...
Tokens:29,946
Snippets:331
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install @openai/chatkit-react

Source: https://openai.github.io/chatkit-js/quickstart

Install the React package for ChatKit. Use this before using the React component.

```bash
npm install @openai/chatkit-react
```

--------------------------------

### Install @openai/chatkit

Source: https://openai.github.io/chatkit-js/quickstart

Install the vanilla JavaScript package for ChatKit. Use this before using the custom element.

```bash
npm install @openai/chatkit
```

--------------------------------

### Vanilla JS ChatKit custom element setup

Source: https://openai.github.io/chatkit-js/quickstart

Vanilla JavaScript setup: creates an openai-chatkit custom element, sets its options with the API URL and domain key, and appends it to a div with id 'chat-root'. The script is a module that imports the package.

```html
<div id="chat-root"></div>
<script type="module">
  import '@openai/chatkit';


  const chatkit = document.createElement('openai-chatkit');


  chatkit.setOptions({
    api: {
      url: 'http://localhost:8000/chatkit',
      domainKey: 'local-dev',
    },
  });


  document.getElementById('chat-root')?.append(chatkit);
</script>
```

--------------------------------

### Imperative setup: create openai-chatkit element

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Creates an 'openai-chatkit' element imperatively, sets options, and appends it to the document body. Use when you need to configure the component programmatically.

```javascript
const chatkit = document.createElement('openai-chatkit');
chatkit.setOptions({
  /* ... */
});
document.body.append(chatkit);
```

--------------------------------

### Customize ChatKit with React `useChatKit`

Source: https://openai.github.io/chatkit-js/customize

Configure ChatKit options using the React hook `useChatKit`. This example customizes theme, header, history, start screen, composer, and thread item actions. The `control` variable is returned from the hook.

```javascript
import { useChatKit } from '@openai/chatkit-react';


const { control } = useChatKit({
  theme: {
    colorScheme: 'dark',
    radius: 'round',
    color: {
      accent: { primary: '#8B5CF6', level: 2 },
    },
  },
  header: {
    enabled: true,
    rightAction: {
      icon: 'light-mode',
      onClick: () => console.log('Toggle theme'),
    },
  },
  history: {
    enabled: true,
    showDelete: true,
    showRename: true,
  },
  startScreen: {
    greeting: 'How can we help?',
    prompts: [
      {
        label: 'Troubleshoot an issue',
        prompt: 'Help me fix an issue',
        icon: 'lifesaver',
      },
      {
        label: 'Request a feature',
        prompt: 'I have an idea',
        icon: 'lightbulb',
      },
    ],
  },
  composer: {
    placeholder: 'Ask the assistant…',
  },
  threadItemActions: {
    feedback: true,
    retry: true,
  },
});
```

--------------------------------

### chatkit.thread.load.start

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when ChatKit starts loading a thread (initial load or selected from history).

```APIDOC
## `chatkit.thread.load.start`

### Description

Emitted when ChatKit starts loading a thread (initial load or selected from history).

### Event Type

`CustomEvent<{ threadId: string }>`

### Detail Type

`{ threadId: string }`

### Properties

- **threadId** (`string`) - The ID of the thread being loaded.
```

--------------------------------

### sendAction example with widget onAction handler

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/interfaces/openaichatkit

Shows how to handle a widget action client-side and then send it back to the server using chatkit.sendAction. The action is first handled by someClientSideHandling, then sent with the widget item's ID.

```typescript
chatKit.options = {
  // other options...
  widgets: {
    async onAction(action, widgetItem) {
      await someClientSideHandling(action);
      await chatkit.sendAction(action, widgetItem.id);
    },
  },
};
```

--------------------------------

### Customize ChatKit on Web Component with `setOptions`

Source: https://openai.github.io/chatkit-js/customize

Configure ChatKit options on a web component using `setOptions`. This example matches the React version but uses the web component API.

```javascript
chatkit.setOptions({
  theme: {
    colorScheme: 'dark',
    radius: 'round',
    color: {
      accent: { primary: '#8B5CF6', level: 2 },
    },
  },
  header: {
    enabled: true,
    rightAction: {
      icon: 'light-mode',
      onClick: () => console.log('Toggle theme'),
    },
  },
  history: {
    enabled: true,
    showDelete: true,
    showRename: true,
  },
  startScreen: {
    greeting: 'How can we help?',
    prompts: [
      {
        label: 'Troubleshoot an issue',
        prompt: 'Help me fix an issue',
        icon: 'lifesaver',
      },
      {
        label: 'Request a feature',
        prompt: 'I have an idea',
        icon: 'lightbulb',
      },
    ],
  },
  composer: {
    placeholder: 'Ask the assistant…',
  },
  threadItemActions: {
    feedback: true,
    retry: true,
  },
});
```

--------------------------------

### Load ChatKit script in root HTML

Source: https://openai.github.io/chatkit-js/quickstart

Add this script tag once to your root HTML to load the ChatKit script asynchronously. Required for both React and vanilla JavaScript setups.

```html
<script
  src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
  async
></script>
```

--------------------------------

### sendCustomAction()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Sends a custom application-defined action to your backend. See the widget-actions guide for more details.

```APIDOC
## sendCustomAction()

### Description
Sends a custom application-defined action to your backend.

### Method
sendCustomAction

### Signature
```typescript
sendCustomAction(action: {
  payload?: Record<string, unknown>;
  type: string;
}, itemId?: string): Promise<void>;
```

### Parameters
- **action** (object) - Required - The action to send.
  - **payload** (Record<string, unknown>) - Optional - Additional data to send with the action.
  - **type** (string) - Required - The type of the action.
- **itemId** (string) - Optional - The ID of the item associated with the action.

### Returns
- **Promise<void>** - A promise that resolves when the action is sent.

### More Details
See [https://openai.github.io/chatkit-js/guides/widget-actions/](https://openai.github.io/chatkit-js/guides/widget-actions/) for more details.
```

--------------------------------

### addEventListener example: chatkit.error

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Example of adding an event listener for the 'chatkit.error' event. The event detail contains an error object, which is passed to a custom error logger.

```javascript
chatKit.addEventListener('chatkit.error', (event) => {
  logToMyErrorLogger(event.detail.error);
});
```

--------------------------------

### removeEventListener example: chatkit.error

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Example of removing an event listener for the 'chatkit.error' event using a previously defined listener callback.

```javascript
chatKit.removeEventListener('chatkit.error', myErrorListener);
```

--------------------------------

### Vanilla JS: Create openai-chatkit element

Source: https://openai.github.io/chatkit-js

Initialize ChatKit in vanilla JavaScript by creating an 'openai-chatkit' element, setting its options with api url and domainKey, adding CSS classes, and appending it to the document body.

```javascript
function InitChatkit({ clientToken }) {
  const chatkit = document.createElement('openai-chatkit');
  chatkit.setOptions({ api: { url, domainKey } });
  chatkit.classList.add('h-[600px]', 'w-[320px]');
  document.body.appendChild(chatkit);
}
```

--------------------------------

### setOptions()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Applies configuration options to the ChatKit instance. Note that options are not merged; you must provide a full set of options each time.

```APIDOC
## setOptions()

### Description
Applies configuration options to the ChatKit instance. **IMPORTANT**: New options are not merged with existing options. You must provide a full set of options every time.

### Method
setOptions

### Signature
```
setOptions(options: ChatKitOptions): void;
```

### Parameters
- **options** (ChatKitOptions) - Required - The full set of configuration options.

### Returns
`void`
```

--------------------------------

### chatkit.response.start

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when the assistant begins sending a response.

```APIDOC
## `chatkit.response.start`

### Description

Emitted when the assistant begins sending a response.

### Event Type

`CustomEvent<void>`

### Detail Type

`void`

### Properties

- **detail** (`void`) - No additional data is provided with this event.
```

--------------------------------

### Configure ChatKit options with onAction handler

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Shows how to set the `widgets.onAction` handler in `chatKit.options` to handle an action client-side and then send it back to the server using `chatkit.sendAction`. The `widgetItem.id` is used to associate the action with the originating widget item.

```javascript
chatKit.options = {  // other options...  widgets: {    async onAction(action, widgetItem) {      await someClientSideHandling(action);      await chatkit.sendAction(action, widgetItem.id);    },  },};
```

--------------------------------

### chatkit.ready

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when the ChatKit frame has loaded.

```APIDOC
## `chatkit.ready`

### Description

Emitted when the ChatKit frame has loaded. The event provides no additional data.

### Event Type

`CustomEvent<void>`

### Detail Type

`void`

### Properties

- **detail** (`void`) - No additional data is provided with this event.
```

--------------------------------

### getClientSecret

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/hostedapiconfig

Function to get a client token or refresh if the current token is expired. It accepts the current client secret (or null) and returns a Promise that resolves to a new client secret string.

```APIDOC
## getClientSecret

### Description
Function to get a client token or refresh if the current token is expired.

### Signature
```typescript
getClientSecret: (currentClientSecret: string | null) => Promise<string>;
```

### Parameters
- **currentClientSecret** (`string | null`) - The current client secret, or `null` if none exists.

### Returns
- `Promise<string>` - A promise that resolves to the new client secret string.
```

--------------------------------

### Justification type alias definition

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/namespaces/widgets/type-aliases/justification

Defines the Justification type as a union of string literals: 'start', 'center', 'end', 'between', 'around', 'evenly', and 'stretch'. Use this type to specify the alignment of items in a flex container.

```typescript
type Justification =
  | 'start'
  | 'center'
  | 'end'
  | 'between'
  | 'around'
  | 'evenly'
  | 'stretch';
```

--------------------------------

### React: Use ChatKit component with useChatKit hook

Source: https://openai.github.io/chatkit-js

Initialize ChatKit in a React component using the useChatKit hook and render the ChatKit component. Requires a clientToken and api configuration with url and domainKey.

```jsx
function MyChat({ clientToken }) {
  const { control } = useChatKit({
    api: { url, domainKey }
  });


  return (
    <ChatKit
      control={control}
      className="h-[600px] w-[320px]"
    />
  );
}
```

--------------------------------

### Declarative markup: openai-chatkit with script

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Shows declarative HTML markup for the component and a script that retrieves the element by ID and calls setOptions. Use when embedding the component in static HTML.

```html
<openai-chatkit id="chatkit-container"></openai-chatkit>
<script type="module">
  const chatkit = document.getElementById('chatkit-container');
  chatkit.setOptions({
    /* ... */
  });
</script>
```

--------------------------------

### useChatKit(options)

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/functions/usechatkit

A React hook that initializes ChatKit with the provided options and returns an object containing chat methods and state.

```APIDOC
## useChatKit(options)

### Description
A React hook that initializes ChatKit with the provided options and returns an object containing chat methods and state.

### Method
useChatKit

### Signature
function useChatKit(options: UseChatKitOptions): UseChatKitReturn;

### Parameters
- **options** (UseChatKitOptions) - Required - Options for initializing ChatKit.

### Returns
- **UseChatKitReturn** - The return object containing chat methods and state.
```

--------------------------------

### fetchUpdates()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Manually fetches updates from the server. Use this when you've manually updated the thread or thread items and need to sync them with the client.

```APIDOC
## fetchUpdates()

### Description
Manually fetches updates from the server. Use this when you've manually updated the thread or thread items and need to sync them with the client.

### Method
fetchUpdates

### Signature
```
fetchUpdates(): Promise<void>;
```

### Returns
`Promise<void>`
```

--------------------------------

### chatkit.history.open

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when the history view opens.

```APIDOC
## `chatkit.history.open`

### Description

Emitted when the history view opens.

### Event Type

`CustomEvent<void>`

### Detail Type

`void`

### Properties

- **detail** (`void`) - No additional data is provided with this event.
```

--------------------------------

### showHistory()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Opens the thread history view. Intended for apps with custom header or navigation that need to show history programmatically.

```APIDOC
## showHistory()

### Description
Opens the thread history view. Intended for apps with a custom header or navigation that need to show history programmatically (for example, from a custom History button).

### Method
showHistory

### Signature
```
showHistory(): Promise<void>;
```

### Returns
`Promise<void>`
```

--------------------------------

### setOptions method signature

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

TypeScript signature for the `setOptions` method. Applies configuration options to the ChatKit instance. Note that new options are not merged with existing options; you must provide a full set of options every time.

```typescript
setOptions(options: ChatKitOptions): void;
```

--------------------------------

### useChatKit

Source: https://openai.github.io/chatkit-js/quick-reference/use-chatkit

Documentation for the useChatKit React hook, including its parameters and return type.

```APIDOC
## useChatKit(options: UseChatKitOptions): UseChatKitReturn

### Description
Prepares the `<openai-chatkit>` element for React. It keeps the options you provide stable between renders, lifts out event handlers, and returns the imperative helpers exposed by the underlying element.

### Parameters
- **options** (UseChatKitOptions) - Required - The options object combining ChatKitOptions with camel-cased event handlers.

### Returns
- **focusComposer** (() => Promise<void>) - Focuses the composer.
- **setThreadId** ((threadId: string | null) => Promise<void>) - Sets the current thread ID.
- **sendUserMessage** ((params: { text?: string; content?: UserMessageContent[]; reply?: string; attachments?: Attachment[]; newThread?: boolean; toolChoice?: ToolChoice; model?: string }) => Promise<void>) - Sends a user message.
- **setComposerValue** ((params: { text?: string; content?: UserMessageContent[]; reply?: string; attachments?: Attachment[]; files?: File[]; selectedToolId?: string; selectedModelId?: string }) => Promise<void>) - Sets the composer value.
- **fetchUpdates** (() => Promise<void>) - Fetches updates.
- **sendCustomAction** ((action: { type: string; payload?: Record<string, unknown> }, itemId?: string) => Promise<void>) - Sends a custom action.
- **showHistory** (() => Promise<void>) - Shows the history.
- **hideHistory** (() => Promise<void>) - Hides the history.
- **control** (ChatKitControl) - A bundle of stable options plus extracted handlers.
- **ref** (React.RefObject<OpenAIChatKit | null>) - A ref to forward to the `<ChatKit>` component.
```

--------------------------------

### chatkit.tool.change

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when the selected composer tool changes.

```APIDOC
## `chatkit.tool.change`

### Description

Emitted when the selected composer tool changes.

### Event Type

`CustomEvent<{ toolId: string | null }>`

### Detail Type

`{ toolId: string | null }`

### Properties

- **toolId** (`string | null`) - The ID of the newly selected tool, or `null` if no tool is selected.
```

--------------------------------

### ComposerOption

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/composeroption

Type alias for the composer configuration object.

```APIDOC
## ComposerOption

### Description
Type alias for the composer configuration object.

### Type Definition
```typescript
type ComposerOption = {
  attachments?: {
    accept?: Record<string, string[]>;
    enabled: boolean;
    maxCount?: number;
    maxSize?: number | Record<string, number>;
  };
  dictation?: {
    enabled: boolean;
  };
  models?: ModelOption[];
  placeholder?: string;
  tools?: ToolOption[];
};
```

### Properties

#### attachments?
- **Type**: `object` - Optional
- **Description**: Configuration for file attachments in the composer. If not provided, attachments will be disabled.

| Name | Type | Description |
|------|------|-------------|
| `accept?` | `Record<string, string[]>` | The MIME types and extensions that are accepted for file uploads, similar to `showOpenFilePicker`. When not specified, all MIME types and extensions are accepted. |
| `enabled` | `boolean` | Whether file attachments are enabled in the composer. **Default**: `false` |
| `maxCount?` | `number` | The maximum number of attachments that can be sent in a single message. **Default**: `10` |
| `maxSize?` | `number` \| `Record<string, number>` | The maximum size of an attachment in bytes. Provide a number to apply the same limit to every attachment, or a record of MIME type patterns to per-type limits (for example, `{ "image/*": 10 * 1024 * 1024 }`). Add a `"*"` or `""` entry to set the fallback limit for files that do not match another MIME type pattern; otherwise they use the default limit. **Default**: `100 * 1024 * 1024 (100MB)` |

#### dictation?
- **Type**: `object` - Optional
- **Description**: Dictation (voice input) settings for the composer. Disabled when not provided.

| Name | Type | Description |
|------|------|-------------|
| `enabled` | `boolean` | Enable dictation. **Default**: `false` |

#### models?
- **Type**: `ModelOption[]` - Optional
- **Description**: A list of models that users can choose from before sending a message.
- **See**: `ModelOption`

#### placeholder?
- **Type**: `string` - Optional
- **Description**: The placeholder text to show in the composer input.
- **Default**: `'Message the AI'`

#### tools?
- **Type**: `ToolOption[]` - Optional
- **Description**: When provided a list of tool options, the user will be able to select a tool from a menu in the composer.
- **See**: `ToolOption`

```

--------------------------------

### onAction

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/widgetsoption

Optional callback function called when a widget action is triggered. It receives an action object with a type and optional payload, and a widgetItem object containing the widget's id and the widget instance (Card, ListView, or BasicRoot). Returns a Promise that resolves when the action handling is complete.

```APIDOC
## onAction

### Description
Called when a widget action is triggered. See https://openai.github.io/chatkit-js/guides/widget-actions/ for details.

### Signature
```typescript
onAction?: (action: {
  payload?: Record<string, unknown>;
  type: string;
}, widgetItem: {
  id: string;
  widget: Card | ListView | BasicRoot;
}) => Promise<void>;
```

### Parameters
- **action** (object) - Required - The action object containing:
  - **action.payload?** (Record<string, unknown>) - Optional - Additional payload data for the action.
  - **action.type** (string) - Required - The type of the action.
- **widgetItem** (object) - Required - The widget item containing:
  - **widgetItem.id** (string) - Required - The unique identifier of the widget.
  - **widgetItem.widget** (Card | ListView | BasicRoot) - Required - The widget instance, which can be a Card, ListView, or BasicRoot.

### Returns
`Promise<void>` - A promise that resolves when the action handling is complete.
```

--------------------------------

### chatkit.thread.load.end

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when ChatKit finished loading a thread.

```APIDOC
## `chatkit.thread.load.end`

### Description

Emitted when ChatKit finished loading a thread.

### Event Type

`CustomEvent<{ threadId: string }>`

### Detail Type

`{ threadId: string }`

### Properties

- **threadId** (`string`) - The ID of the thread that finished loading.
```

--------------------------------

### CommandsOption

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/commandsoption

Type alias for the CommandsOption configuration object.

```APIDOC
## CommandsOption

### Description
Type alias for the configuration of the "/" command menu.

### Type Definition
```typescript
type CommandsOption = {
  enabled: boolean;
  onSearch?: (query: string) => Promise<Command[]>;
  onSelect?: (command: Command) => Promise<void | CommandSelection>;
};
```

### Properties

#### enabled
- **type**: boolean
- **description**: Enables the "/" command menu, including applicable built-in composer actions.

#### onSearch()?
- **type**: (query: string) => Promise<Command[]>
- **description**: Returns integration-defined commands matching the input query.
- **Parameters**:
  - `query` (string) - The search query.
- **Returns**: `Promise<Command[]>`

#### onSelect()?
- **type**: (command: Command) => Promise<void | CommandSelection>
- **description**: Runs a command. Return an entity to insert it, another menu to continue command selection, or nothing when the command only performs an effect.
- **Parameters**:
  - `command` (Command) - The command to run.
- **Returns**: `Promise<void | CommandSelection>`
```

--------------------------------

### sendAction()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Sends an action to the server, optionally associated with a widget item. Use this to handle actions triggered by widgets or custom UI.

```APIDOC
## sendAction()

### Description
Sends an action to the server. The action can be associated with a widget item if needed.

### Method
sendAction

### Signature
```
sendAction(action: { payload?: Record<string, unknown>; type: string; }, itemId?: string): Promise<void>;
```

### Parameters
- **action** (object) - Required - The action object containing a type and optional payload.
  - **action.payload** (Record<string, unknown>) - Optional - Additional data for the action.
  - **action.type** (string) - Required - The type of the action.
- **itemId** (string) - Optional - The ID of the WidgetItem that the action is associated with. Needed if the action was triggered by a widget and you want to send it back to the server for additional handling.

### Returns
`Promise<void>`

### Example
```js
chatKit.options = {
  // other options...
  widgets: {
    async onAction(action, widgetItem) {
      await someClientSideHandling(action);
      await chatkit.sendAction(action, widgetItem.id);
    },
  },
};
```
```

--------------------------------

### Input Type Alias

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/namespaces/widgets/type-aliases/input

Defines the structure of an Input widget configuration object.

```APIDOC
## Input Type Alias

### Description
Defines the structure of an Input widget configuration object.

### Type Alias
```typescript
type Input = {
  allowAutofillExtensions?: boolean;
  autoFocus?: boolean;
  autoSelect?: boolean;
  defaultValue?: string;
  disabled?: boolean;
  gutterSize?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  id?: string;
  inputType?: 'number' | 'email' | 'text' | 'password' | 'tel' | 'url';
  key?: string;
  name: string;
  pattern?: string;
  pill?: boolean;
  placeholder?: string;
  required?: boolean;
  size?: ControlSize;
  type: 'Input';
  variant?: 'soft' | 'outline';
};
```

### Properties

#### allowAutofillExtensions?
- **Type**: `boolean` - Optional - Whether to allow autofill extensions.

#### autoFocus?
- **Type**: `boolean` - Optional - Whether the input should automatically focus on mount.

#### autoSelect?
- **Type**: `boolean` - Optional - Whether to automatically select the input content on focus.

#### defaultValue?
- **Type**: `string` - Optional - The default value of the input.

#### disabled?
- **Type**: `boolean` - Optional - Whether the input is disabled.

#### gutterSize?
- **Type**: `'2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'` - Optional - The size of the gutter around the input.

#### id?
- **Type**: `string` - Optional - The unique identifier for the input.

#### inputType?
- **Type**: `'number' | 'email' | 'text' | 'password' | 'tel' | 'url'` - Optional - The type of the input.

#### key?
- **Type**: `string` - Optional - A key for the input.

#### name
- **Type**: `string` - Required - The name of the input.

#### pattern?
- **Type**: `string` - Optional - A regular expression pattern for validation.

#### pill?
- **Type**: `boolean` - Optional - Whether the input has a pill shape.

#### placeholder?
- **Type**: `string` - Optional - The placeholder text for the input.

#### required?
- **Type**: `boolean` - Optional - Whether the input is required.

#### size?
- **Type**: `ControlSize` - Optional - The size of the input.

#### type
- **Type**: `'Input'` - Required - The type of the widget, must be 'Input'.

#### variant?
- **Type**: `'soft' | 'outline'` - Optional - The visual variant of the input.
```

--------------------------------

### CommandsOption

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/commandsoption

Type alias for the options object used to configure the slash command menu in ChatKit.

```APIDOC
## CommandsOption

### Description
Type alias for the options object used to configure the slash command menu in ChatKit.

### Type Definition
```typescript
type CommandsOption = {
  enabled: boolean;
  onSearch?: (query: string) => Promise<Command[]>;
  onSelect?: (command: Command) => Promise<void | CommandSelection>;
};
```

### Properties

#### enabled
- **Type**: `boolean`
- **Required**: Yes
- **Description**: Enables the "/" command menu, including applicable built-in composer actions.

#### onSearch?
- **Type**: `(query: string) => Promise<Command[]>`
- **Required**: No
- **Description**: Returns integration-defined commands matching the input query.

##### Parameters
- **query** (`string`) - The search query string.

##### Returns
- `Promise<Command[]>` - A promise that resolves to an array of matching commands.

#### onSelect?
- **Type**: `(command: Command) => Promise<void | CommandSelection>`
- **Required**: No
- **Description**: Runs a command. Return an entity to insert it, another menu to continue command selection, or nothing when the command only performs an effect.

##### Parameters
- **command** (`Command`) - The command to execute.

##### Returns
- `Promise<void | CommandSelection>` - A promise that resolves to nothing, a `CommandSelection` to insert an entity, or another menu to continue selection.
```

--------------------------------

### focusComposer()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Focuses the composer input field.

```APIDOC
## focusComposer()

### Description
Focuses the composer input field.

### Method
focusComposer

### Signature
```
focusComposer(): Promise<void>;
```

### Returns
`Promise<void>`
```

--------------------------------

### sendUserMessage()

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

Sends a user message with optional attachments, structured content, model, thread, reply, text, and tool choice.

```APIDOC
## sendUserMessage()

### Description
Sends a user message. Supports attachments, structured content, model selection, thread management, and tool choice.

### Method
sendUserMessage

### Signature
```
sendUserMessage(params: {
  attachments?: Attachment[];
  content?: UserMessageContent[];
  model?: string;
  newThread?: boolean;
  reply?: string;
  text?: string;
  toolChoice?: ToolChoice;
}): Promise<void>;
```

### Parameters
- **params** (object) - Required - The parameters for the message.
  - **params.attachments** (Attachment[]) - Optional - Attachments associated with the user message. Must already be uploaded by your server.
  - **params.content** (UserMessageContent[]) - Optional - Use instead of `text` when sending structured content such as entity tags.
  - **params.model** (string) - Optional - The model to use.
  - **params.newThread** (boolean) - Optional - Whether to start a new thread.
  - **params.reply** (string) - Optional - The reply to a previous message.
  - **params.text** (string) - Optional - The text of the message.
  - **params.toolChoice** (ToolChoice) - Optional - The tool choice. Maps directly to backend `inference_options`. Does not update the selected tool in the composer; use `setComposerValue` for that.

### Returns
`Promise<void>`
```

--------------------------------

### HostedApiConfig

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/hostedapiconfig

Defines the HostedApiConfig type with a getClientSecret function for retrieving or refreshing a client token.

```APIDOC
## HostedApiConfig

### Description
Defines the shape of the configuration object for a hosted API client, including a function to retrieve or refresh the client secret.

### Type Definition
```typescript
type HostedApiConfig = {
  getClientSecret: (currentClientSecret: string | null) => Promise<string>;
};
```

### Properties
#### getClientSecret()

**Signature:**
```typescript
getClientSecret: (currentClientSecret: string | null) => Promise<string>;
```

**Description:**
Function to get a client token or refresh if the current token is expired.

##### Parameters
- **currentClientSecret** (`string | null`) - The current client secret or null if none exists.

##### Returns
- `Promise<string>` - A promise that resolves to the client secret.
```

--------------------------------

### WidgetsOption.onAction

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/widgetsoption

Called when a widget action is triggered. See https://openai.github.io/chatkit-js/guides/widget-actions/ for details.

```APIDOC
## onAction

### Description
Called when a widget action is triggered. See https://openai.github.io/chatkit-js/guides/widget-actions/ for details.

### Signature
```typescript
onAction?: (action: {
  payload?: Record<string, unknown>;
  type: string;
}, widgetItem: {
  id: string;
  widget: Card | ListView | BasicRoot;
}) => Promise<void>;
```

### Parameters
- **action** (object) - Required - The action object containing the action type and optional payload.
  - **action.payload?** (Record<string, unknown>) - Optional - Additional data associated with the action.
  - **action.type** (string) - Required - The type of the action.
- **widgetItem** (object) - Required - The widget item that triggered the action.
  - **widgetItem.id** (string) - Required - The unique identifier of the widget.
  - **widgetItem.widget** (Card | ListView | BasicRoot) - Required - The widget instance.

### Returns
`Promise<void>` - A promise that resolves when the action handling is complete.
```

--------------------------------

### Form

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/namespaces/widgets/type-aliases/form

Type alias for a Form widget configuration. It includes optional properties for direction, id, key, and onSubmitAction, along with a required type field and BoxBaseProps.

```APIDOC
## Form

### Description
Type alias for a Form widget configuration.

### Type Declaration
```typescript
type Form = {
  direction?: 'row' | 'col';
  id?: string;
  key?: string;
  onSubmitAction?: ActionConfig;
  type: 'Form';
} & BoxBaseProps;
```

### Properties

#### direction?
- **Type**: `"row" | "col"`
- **Optional**: Yes
- **Description**: Layout direction of the form.

#### id?
- **Type**: `string`
- **Optional**: Yes
- **Description**: Identifier for the form.

#### key?
- **Type**: `string`
- **Optional**: Yes
- **Description**: Key for the form.

#### onSubmitAction?
- **Type**: `ActionConfig`
- **Optional**: Yes
- **Description**: Action configuration for form submission.

#### type
- **Type**: `'Form'`
- **Optional**: No
- **Description**: Discriminator field indicating this is a Form widget.

### Inherited Properties
- **BoxBaseProps**: Base properties for box layout.
```

--------------------------------

### Select Type Alias

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/select

Defines the structure of a Select widget configuration, including required and optional properties.

```APIDOC
## Select Type Alias

### Description
Defines the structure of a Select widget configuration, including required and optional properties.

### Type Definition
```typescript
type Select = {
  block?: boolean;
  clearable?: boolean;
  defaultValue?: string;
  disabled?: boolean;
  id?: string;
  key?: string;
  name: string;
  onChangeAction?: ActionConfig;
  options: {
    label: string;
    value: string;
  }[];
  pill?: boolean;
  placeholder?: string;
  size?: ControlSize;
  type: 'Select';
  variant?: ControlVariant;
};
```

### Properties

#### `block?` (optional)
- Type: `boolean`
- Description: Whether the select should be displayed as a block element.

#### `clearable?` (optional)
- Type: `boolean`
- Description: Whether the select can be cleared.

#### `defaultValue?` (optional)
- Type: `string`
- Description: The default value of the select.

#### `disabled?` (optional)
- Type: `boolean`
- Description: Whether the select is disabled.

#### `id?` (optional)
- Type: `string`
- Description: The unique identifier for the select.

#### `key?` (optional)
- Type: `string`
- Description: A key for the select component.

#### `name` (required)
- Type: `string`
- Description: The name of the select field.

#### `onChangeAction?` (optional)
- Type: `ActionConfig`
- Description: Configuration for the action triggered when the select value changes.

#### `options` (required)
- Type: `{ label: string; value: string; }[]`
- Description: The list of options to display in the select.
  - `label` (string) - The display label for the option.
  - `value` (string) - The value associated with the option.

#### `pill?` (optional)
- Type: `boolean`
- Description: Whether the select should be styled as a pill.

#### `placeholder?` (optional)
- Type: `string`
- Description: The placeholder text for the select.

#### `size?` (optional)
- Type: `ControlSize`
- Description: The size of the select control.

#### `type` (required)
- Type: `'Select'`
- Description: The type of the widget, must be `'Select'`.

#### `variant?` (optional)
- Type: `ControlVariant`
- Description: The visual variant of the select control.
```

--------------------------------

### showHistory method signature

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

TypeScript signature for the `showHistory` method. Opens the thread history view. Intended for apps with a custom header or navigation that need to show history programmatically.

```typescript
showHistory(): Promise<void>;
```

--------------------------------

### Textarea Type Alias

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/textarea

Defines the structure of a Textarea widget configuration object.

```APIDOC
## Textarea Type Alias

### Description
Defines the structure of a Textarea widget configuration object.

### Type Definition
```typescript
type Textarea = {
  allowAutofillExtensions?: boolean;
  autoFocus?: boolean;
  autoResize?: boolean;
  autoSelect?: boolean;
  defaultValue?: string;
  disabled?: boolean;
  gutterSize?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  id?: string;
  key?: string;
  maxRows?: number;
  name: string;
  pattern?: string;
  placeholder?: string;
  required?: boolean;
  rows?: number;
  size?: ControlSize;
  type: 'Textarea';
  variant?: 'soft' | 'outline';
};
```

### Properties
#### allowAutofillExtensions?
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Whether to allow autofill extensions.

#### autoFocus?
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Whether the textarea should automatically focus on mount.

#### autoResize?
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Whether the textarea should automatically resize to fit its content.

#### autoSelect?
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Whether the textarea should automatically select its content on focus.

#### defaultValue?
- **Type**: `string`
- **Optional**: Yes
- **Description**: The default value of the textarea.

#### disabled?
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Whether the textarea is disabled.

#### gutterSize?
- **Type**: `'2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`
- **Optional**: Yes
- **Description**: The size of the gutter (spacing) around the textarea.

#### id?
- **Type**: `string`
- **Optional**: Yes
- **Description**: The HTML id attribute for the textarea.

#### key?
- **Type**: `string`
- **Optional**: Yes
- **Description**: A React key for the textarea component.

#### maxRows?
- **Type**: `number`
- **Optional**: Yes
- **Description**: The maximum number of rows the textarea can grow to.

#### name
- **Type**: `string`
- **Required**: Yes
- **Description**: The name attribute for the textarea.

#### pattern?
- **Type**: `string`
- **Optional**: Yes
- **Description**: A regular expression pattern for validation.

#### placeholder?
- **Type**: `string`
- **Optional**: Yes
- **Description**: Placeholder text for the textarea.

#### required?
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Whether the textarea is required.

#### rows?
- **Type**: `number`
- **Optional**: Yes
- **Description**: The number of rows to display.

#### size?
- **Type**: `ControlSize`
- **Optional**: Yes
- **Description**: The size of the textarea (e.g., small, medium, large).

#### type
- **Type**: `'Textarea'`
- **Required**: Yes
- **Description**: The type of the widget, must be 'Textarea'.

#### variant?
- **Type**: `'soft' | 'outline'`
- **Optional**: Yes
- **Description**: The visual variant of the textarea.
```

--------------------------------

### Render ChatKit component with control prop

Source: https://openai.github.io/chatkit-js/quick-reference/chatkit-component

Renders the ChatKit component, passing the control object from useChatKit. Extra props are forwarded to the underlying openai-chatkit element.

```jsx
<ChatKit control={control} {...props} />
```

--------------------------------

### chatkit.response.end

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when the assistant finishes sending a response.

```APIDOC
## `chatkit.response.end`

### Description

Emitted when the assistant finishes sending a response.

### Event Type

`CustomEvent<void>`

### Detail Type

`void`

### Properties

- **detail** (`void`) - No additional data is provided with this event.
```

--------------------------------

### chatkit.deeplink

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Emitted when a chatkit-link:// deeplink is clicked.

```APIDOC
## `chatkit.deeplink`

### Description

Emitted when a `chatkit-link://` deeplink is clicked.

### Event Type

`CustomEvent<{ data?: Record<string, unknown>; name: string }>`

### Detail Type

`{ data?: Record<string, unknown>; name: string }`

### Properties

- **data** (`Record<string, unknown>`, optional) - Additional data related to the deeplink.
- **name** (`string`) - The deeplink name.
```

--------------------------------

### fetchUpdates method signature

Source: https://openai.github.io/chatkit-js/api/openai/chatkit/interfaces/openaichatkit

TypeScript signature for fetchUpdates, which manually fetches updates from the server. Use after manually updating the thread or thread items to sync with the client.

```typescript
fetchUpdates(): Promise<void>;
```

--------------------------------

### chatkit.log

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/chatkitevents

Diagnostic events that can be used for logging/analytics.

```APIDOC
## `chatkit.log`

### Description

Diagnostic events that can be used for logging/analytics.

### Event Type

`CustomEvent<{ data?: Record<string, unknown>; name: string }>`

### Detail Type

`{ data?: Record<string, unknown>; name: string }`

### Properties

- **data** (`Record<string, unknown>`, optional) - Additional data for the log event.
- **name** (`string`) - A name identifying the log event.
```

--------------------------------

### GrayscaleOptions

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/grayscaleoptions

Type alias for configuring a grayscale palette. It defines the hue, optional shade, and tint properties.

```APIDOC
## GrayscaleOptions

### Description
Type alias for configuring a grayscale palette derived from a given hue.

### Type Definition
```typescript
type GrayscaleOptions = {
  hue: number;
  shade?: -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4;
  tint: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
};
```

### Properties

#### hue
- **Type**: `number`
- **Required**: Yes
- **Description**: Hue in degrees (0–360).

#### shade?
- **Type**: `-4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4`
- **Required**: No
- **Description**: Optional shade adjustment applied to the palette.

#### tint
- **Type**: `0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9`
- **Required**: Yes
- **Description**: Tint step applied to the grayscale palette.

```

--------------------------------

### React ChatKit component with useChatKit

Source: https://openai.github.io/chatkit-js/quickstart

React component that uses useChatKit to configure the API and renders the ChatKit component with a custom class. The api.url and domainKey are set to local development values.

```jsx
import { ChatKit, useChatKit } from '@openai/chatkit-react';


export function SupportChat() {
  const { control } = useChatKit({
    api: {
      url: 'http://localhost:8000/chatkit',
      domainKey: 'local-dev',
    },
  });


  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
```

--------------------------------

### sendCustomAction(action, itemId?)

Source: https://openai.github.io/chatkit-js/api/openai/chatkit-react/interfaces/openaichatkit

Sends a custom application-defined action to your backend. The action object must include a type and an optional payload. An optional itemId can be provided.

```APIDOC
## sendCustomAction(action, itemId?)

### Description
Sends a custom application-defined action to your backend. See https://openai.github.io/chatkit-js/guides/widget-actions/ for more details.

### Method
sendCustomAction

### Signature
```typescript
sendCustomAction(action: {
  payload?: Record<string, unknown>;
  type: string;
}, itemId?: string): Promise<void>;
```

### Parameters
- **action** (object) - Required - The custom action to send.
  - **payload** (Record<string, unknown>) - Optional - Additional data for the action.
  - **type** (string) - Required - The type of the action.
- **itemId** (string) - Optional - The ID of the item associated with the action.

### Returns
Promise<void> - Resolves when the action is sent.
```
Tokens:
Raw