Widget Package (@ticket0-ai/widget)

Install the Ticket0 widget as a React component or headless primitive for full control.

The @ticket0-ai/widget package provides a React component and headless primitives for the chat widget, giving you full control over initialization, theming, and UI composition.

Installation

npm install @ticket0-ai/widget
# or
pnpm add @ticket0-ai/widget

Peer dependencies: react >= 18, react-dom >= 18

Quick start

Drop Ticket0Chat into your app. It fetches workspace theme, color, welcome message, and agent name from the Ticket0 app automatically.

import { Ticket0Chat } from "@ticket0-ai/widget"

export default function App() {
  return (
    <>
      <YourApp />
      <Ticket0Chat workspaceId="ws_your_workspace_id" />
    </>
  )
}

Props

All props are optional except workspaceId. Server config is fetched from your workspace and merged with any props you provide (configMode: "merge" is the default).

Prop	Type	Default	Description
`workspaceId`	`string`	required	Your workspace slug or ID
`apiUrl`	`string`	`https://app.ticket0.ai`	Base URL of the Ticket0 app
`configMode`	`"merge" \| "server" \| "local"`	`"merge"`	Config source strategy
`theme`	`"light" \| "dark" \| "system"`	`"system"`	Color theme
`primaryColor`	`string`	server value	Primary/accent hex color
`position`	`"bottom-right" \| "bottom-left"`	server value	Widget position
`welcomeMessage`	`string`	server value	Greeting shown before first message
`agentName`	`string`	server value	Agent display name in header
`defaultOpen`	`boolean`	`false`	Start the widget open
`hideOnMobile`	`boolean`	`false`	Hide on screens ≤ 640px

Config modes

Mode	Behaviour
`"merge"` (default)	Fetch server config, then apply any provided props as overrides
`"server"`	Use workspace server config only — props are ignored
`"local"`	Use props only — skip the server config fetch entirely

Headless / composable mode

For full UI control, use Ticket0Provider with the individual primitives.

import {
  Ticket0Provider,
  Ticket0Launcher,
  Ticket0ChatWindow,
  Ticket0Trigger,
} from "@ticket0-ai/widget"

function MyApp() {
  return (
    <Ticket0Provider workspaceId="ws_your_workspace_id" theme="dark">
      <Ticket0Launcher />
      <Ticket0ChatWindow />

      <Ticket0Trigger>
        <button className="my-chat-button">Talk to us</button>
      </Ticket0Trigger>
    </Ticket0Provider>
  )
}

Hooks

`useTicket0()`

Returns the full chat state and controls.

import { useTicket0 } from "@ticket0-ai/widget"

function CustomChatButton() {
  const { open, isOpen, unreadCount } = useTicket0()

  return (
    <button onClick={open}>
      Chat with us
      {unreadCount > 0 && <span>{unreadCount}</span>}
    </button>
  )
}

`useTicket0Unread()`

Returns just the unread count (optimised for badge displays).

`useTicket0Config()`

Returns the resolved config (server + overrides merged). Returns null while loading.

Pre-filling customer identity

If your users are signed in, pass their identity so support agents see who they're talking to:

<Ticket0Chat
  workspaceId="ws_your_workspace_id"
  customer={{
    email: user.email,
    name: user.name,
    externalId: user.id,
  }}
/>

The customer's identity is visible in the ticket view and linked to their customer record in Ticket0.

TypeScript

Full type exports are included:

import type {
  Ticket0ChatProps,
  Ticket0ProviderProps,
  WidgetMessage,
  ResolvedConfig,
  Theme,
  Position,
  ConfigMode,
} from "@ticket0-ai/widget"

Widget Package (@ticket0-ai/widget)

On this page