Reference

Reference: @zean-chat/react

The ZeanChat component and the useZean hook, for Next.js, React Router, TanStack Start and React.

Updated October 18, 2026

The samples show app_your_app_key. Open this guide from App settings > Developers > Getting started to see your App’s key in them.

Install the package, then render ZeanChat once, in what wraps all your pages. See Install the chat on a React site.

Terminal

npm install @zean-chat/react

Exports

Name	Type	Description
`ZeanChat`	`(props: ZeanChatProps) => null`	Shows the chat. It renders nothing itself: the chat lives in its own frame and stays open from page to page.
`useZean()`	`() => ZeanControls`	Opens and closes the chat, and follows the unread count. Works in any component, before the chat has loaded.
`ZeanChatProps`	`interface`	The props of `ZeanChat`.
`ZeanControls`	`interface`	What `useZean()` returns.
`ZeanUser`	`interface`	The signed-in person, below.
`ZeanAttributes`	`Record<string, ZeanAttributeValue>`	The Contact’s attributes: `{ city: "Douala", orders: 12 }`.
`ZeanLocale`	`'fr' \| 'en'`	One of the chat’s languages.

ZeanChat props

Name	Type	Description
`appKey`	`string`	Required. The App’s public key, in App settings > Developers > Getting started.
`user`	`ZeanUser`	Optional. While a person is signed in: `{ id, name, email }`. Leave it out when nobody is: a person who was signed in is signed out. Left out while your app is still loading the user, it signs no one out. The same values on each render change nothing. See Identify your Contacts.
`attributes`	`ZeanAttributes`	Optional. What you know about the person, shown on the Contact’s profile. Sent again on each change. See Custom attributes.
`locale`	`'fr' \| 'en'`	Optional. The chat’s language. Without it: the browser’s, when the chat speaks it, else the App’s default language. Read when the page loads.
`tabAlert`	`boolean`	Optional. The Tab alert: while the Contact has replies to read, your tab’s title starts with their count and its icon gets a red dot. On by default; `false` turns it off. See Show the unread count.

JSX

<ZeanChat  appKey="app_your_app_key"  locale="en"  user={user ? { id: user.id, name: user.name, email: user.email } : undefined}  attributes={{ plan: "pro", orders: 12 }}/>

useZean()

Name	Type	Description
`open()`	`() => void`	Opens the chat.
`close()`	`() => void`	Closes the chat.
`toggle()`	`() => void`	Opens the chat when closed, closes it otherwise.
`identify()`	`(user: ZeanUser) => void`	The person signed in. The first device to bring their ID joins their Conversation at once; another one first asks them for a code sent by email. See Identify your Contacts.
`signOut()`	`() => void`	The person signed out: the chat starts over, anonymous.
`setAttributes()`	`(attributes: ZeanAttributes) => void`	Joined to the attributes sent before. Refused values are reported in the console. See Custom attributes.
`unreadCount`	`number`	The number of replies the Contact has not read, updated on every change. 0 on the server.

JSX

import { useZean } from "@zean-chat/react";export function HelpButton() {  const { open, unreadCount } = useZean();  return <button onClick={open}>Help ({unreadCount})</button>;}

ZeanUser

Name	Type	Description
`id`	`string \| number`	Required. Your own ID for the person, as text or a number, 200 characters at most. The same ID on your website and in your mobile app is one person.
`name`	`string`	Optional. Their name, on their Contact profile.
`email`	`string`	Optional. The code that adds another device goes to this address: without it, a second device can never join the Contact.
`phone`	`string`	Optional. Their phone, on their Contact profile.
`language`	`string`	Optional. Their language, any one, as a tag such as `pt` or `pt-BR`. Without it, their device’s is kept. It does not change the chat’s language.

The package carries the “use client” directive: with Next.js, ZeanChat goes in the root layout with nothing else to set.