React components (@agentimhq/react) API

Generated from the source and its doc comments (sdk/react/src/components.tsx, sdk/react/src/files.tsx, sdk/react/src/hooks.ts, sdk/react/src/format.ts).

npm install @agentimhq/react @agentimhq/client-web

Functions

AgentIM

function AgentIM(

The client, plus the texts, the replaceable parts, who “I” am (for my own messages) and how dates are shown (the user’s own locale and time zone unless given).

AIBadge

function AIBadge()

The AI mark (EU AI Act art. 50): drawn next to every agent’s name and message, also under a replaced Message component.

ConnectionBanner

function ConnectionBanner()

A line saying what the connection is doing (offline, reconnecting, waiting for network); nothing while connected.

ConversationList

function ConversationList({ selected, onSelect, search = true }: { selected?: string; onSelect(convId: string): void; search?: boolean })

The conversations, newest first, with a search box that filters by title and last message.

MessageList

function MessageList({ convId, notices = [], onOpenThread }: { convId: string; notices?: Notice<ReactNode>[]; onOpenThread?(threadId: string): void })

The messages, oldest first, in runs per sender with day separators and “New messages” where the unread ones started; scrolled to the newest, keeps its place when older ones load, and offers a way back down.

TypingIndicator

function TypingIndicator({ convId, names }: { convId: string; names?: (ids: string[]) => string[] })

Who is typing, by name (from the members), with the three dots.

Composer

function Composer({ convId, attach = true }: { convId: string; attach?: boolean })

The message box: Enter sends, Shift+Enter adds a line, it grows with the text; a paperclip, drag and drop and paste send files (attach={false} hides them). Replaced by a notice once the person is no longer a member.

MemberList

function MemberList({ convId }: { convId: string })

The conversation’s members; agents carry the AI mark.

HandoffNotice

function HandoffNotice({ convId }: { convId: string })

Says when an agent hands the conversation to a person, and when it is back (docs/en/design/agents.md).

ApprovalCards

function ApprovalCards({ convId }: { convId: string })

Operations an assistant waits to have approved (docs/en/design/assistants.md), as cards for the people who decide them: what it wants to do, the key values, Approve and Decline; after a decision, the outcome. Shows nothing for people who don’t decide. Part of Chat.

Inbox

function Inbox(props: { types?: string[]; extraItems?: InboxItem[]; renderItem?(p: InboxDetailProps): ReactNode; onOpen?(convId: string): void })

The approval inbox (docs/en/design/chat-components.md): everything waiting for this person across conversations. onOpen(convId) opens a conversation in your app.

InboxBadge

function InboxBadge({ label = true }: { label?: boolean })

How many items wait in the inbox, for your navigation.

ConversationSteps

function ConversationSteps({ convId }: { convId: string })

Steps an agent reports without tying them to a message (docs/en/design/chat-components.md).

Thread

function Thread({ convId, threadId, onClose }: { convId: string; threadId: string; onClose?(): void })

A conversation’s thread, beside or over the messages (docs/en/design/messaging.md): its root, its replies and a composer that answers in it.

PinnedMessages

function PinnedMessages({ convId, onOpen }: { convId: string; onOpen?(pins: any[]): void })

The pinned messages of a conversation: the latest one and how many.

Chat

function Chat({ convId, title, subtitle }: { convId: string; title?: ReactNode; subtitle?: ReactNode })

A whole chat window (the customer-service widget): header, status, messages, typing, composer.

ImageViewer

function ImageViewer({ convId, message: m, thumb, strings, onClose }: { convId: string; message: Message; thumb?: string; strings: Strings; onClose(): void })

The enlarged thumbnail; “View original” loads the full image in its place.

ImageMessage

function ImageMessage({ convId, message: m, strings }: { convId: string; message: Message; strings: Strings })

An image message: the thumbnail at its proportions (at most 240 × 240) with its caption and upload progress; tapping opens the viewer.

FileMessage

function FileMessage({ convId, message: m, strings }: { convId: string; message: Message; strings: Strings })

A file message: a card with the type’s icon, the name, the size and upload progress; clicking downloads the file.

AttachButton

function AttachButton({ strings, onFiles }: { strings: Strings; onFiles(files: File[]): void })

The paperclip: picks files and sends each.

AgentIMProvider

function AgentIMProvider({ client, children }: { client: Client; children?: ReactNode })

Gives the hooks their client (the components use AgentIM, which includes it).

useClient

function useClient(): Client

The client given to the provider.

useObservable

function useObservable<T>(o: Readable<T>): T

The current value of an observable, re-rendering on change.

useConnection

function useConnection(): Connection

The connection state, re-rendering on change.

useConversations

function useConversations(): any[]

The conversation list, re-rendering on change.

useMessages

function useMessages(convId: string): MessagesState

One conversation’s messages, oldest first, with paging back.

useSend

function useSend(convId: string)

Sends to a conversation; the message shows at once and is sent when it can be.

useTyping

function useTyping(convId: string)

Who is typing in the conversation (user ids), and notify() to say that I am.

useFileUrl

function useFileUrl(convId: string, payload: any, variant: 'thumb' | 'original' = 'thumb', opts: { blob?: boolean } = {}): { url?: string; error?: string }

The address to show a file’s thumbnail (thumb; a small image is its own) or to read it: a local copy while this tab sends it, then the server’s. error when it is gone (expired, deleted).

formatTime

function formatTime(t: number, w: When = {}): string

“2:41 PM” (or the locale’s own way).

formatDay

function formatDay(t: number, w: When = {}): string

A day separator: “Today”, “Yesterday”, “Monday”, “Mar 3”, “Mar 3, 2025”.

formatShort

function formatShort(t: number, w: When = {}): string

In a conversation list: the time today, “Yesterday”, the weekday this week, else a short date.

layout

function layout<M extends Laid>(messages: M[], w: When = {}, unreadFrom?: number): Row<M>[]

Rows for a message list: a run is one sender’s messages less than five minutes apart on one day (iMessage, Slack); a recalled message ends a run. unreadFrom is the index of the first unread message, if any.

initials

function initials(name: string | undefined): string

Up to two initials: “Ada Lovelace” → “AL”, “aria” → “A”.

avatarColor

function avatarColor(id: string | undefined, n: number): number

The same colour for the same id, everywhere (an index into the avatar palette).

unreadIndex

function unreadIndex(messages: { sender_id?: string; key: string; mine?: boolean }[], unread: number, me?: string): number | undefined

Where “New messages” goes when a conversation opens with unread unread: above the unread-th message from the end that is not mine.

interleave

function interleave<M extends Laid, N>(rows: Row<M>[], notices: Notice<N>[]): Item<M, N>[]

Notices merged into the rows by seq: a notice goes before the first message with a later seq (local messages, without one, come last) and ends the run around it.

ended

function ended(conv: { ended?: any; members?: any[] } | undefined, me?: string): Ended | undefined

Whether this person left, was removed from or saw the conversation closed: it stays readable, and nothing can be sent (L4).

fileType

function fileType(name?: string, mime?: string): FileType

The icon a file gets from its name and type: pdf, doc, sheet, slides, archive, audio, video, code, image or other.

formatBytes

function formatBytes(n: number, locale?: string): string

“12 KB”, “3.4 MB”: decimal units, as the platforms’ own file browsers show them.

fitBox

function fitBox(width?: number, height?: number, max = 240): { width: number; height: number }

The size an image is shown at: its proportions, at most max on each side.

shortName

function shortName(name: string, max = 32): string

A long name with its start and its extension kept: “Quarterly re…port.pdf”.

formatValue

function formatValue(v: unknown, format: string | undefined, w: When = {}): string

A card value as the viewer reads it (docs/en/design/chat-components.md): numbers, money, percentages and dates in their own locale. format is text, number, currency:XXX, date (YYYY-MM-DD, a calendar day: no time zone shift), datetime (ISO 8601, in the viewer’s time zone) or percent (0.4 → 40%). Values that don’t fit the format are shown as they are.

tone

function tone(t: unknown): Tone

A tone from a card’s JSON (neutral for anything unknown).

foldStep

function foldStep(list: Step[], p: { kind?: string; text?: string; data?: any; at?: number }): Step[]

Folds progress side events into steps, in order (docs/en/design/chat-components.md): a plan lists them, a step sets one; tool_call / tool_result without ids become a step each. Returns the next list (the input is not changed).

formatAgo

function formatAgo(t: number, w: When = {}): string

“3 min”, “2 hr”, “5 days”: how long something has waited (inbox rows, docs/en/design/chat-components.md).

MessageProps

interface MessageProps

What a message component gets: replace Message in components to draw messages your way.

MessageProps.message

message: Message

The message to show.

MessageProps.convId

convId: string

The conversation (to read the message’s file).

MessageProps.mine

mine: boolean

Whether I sent it (shown on the right).

MessageProps.first

first: boolean

First and last of a run from one sender (the bubble’s corners, the time).

MessageProps.last

last: boolean

Whether it ends a run of messages from the same sender (shows the time).

MessageProps.time

time?: string

The time to show under the message (“2:41 PM”), on the last of a run.

MessageProps.strings

strings: Strings

The interface texts in the current language.

MessageProps.onRetry

onRetry(): void

Sends a failed message again.

MessageProps.onDiscard

onDiscard(): void

Drops a failed message.

MessageProps.onFeedback

onFeedback(rating: 'up' | 'down'): void

Rates an agent’s message.

MessageProps.onRespond

onRespond(blockId: string, r: { action?: string; values?: Record<string, unknown> }): void

Answers a card block: a button action or form values.

MessageProps.onEdit

onEdit?(text: string): void

Set when I may edit this message (mine, sent, plain text).

MessageProps.onRecall

onRecall?(): void

Set when I may delete it for everyone (mine, sent).

MessageProps.onStop

onStop?(): void

Set while an agent’s reply streams: interrupt it.

MessageProps.onReact

onReact?(key: string, on: boolean): void

Adds (on) or removes my reaction (docs/en/design/messaging.md).

MessageProps.onOpenThread

onOpenThread?(): void

Set when the app shows threads: opens this message’s thread.

ConversationItemProps

interface ConversationItemProps

What a conversation list row gets: replace ConversationItem in components to draw rows your way.

ConversationItemProps.conversation

conversation: any

The conversation (title, last message, unread count, members…).

ConversationItemProps.selected

selected: boolean

Whether it is the open conversation.

ConversationItemProps.onSelect

onSelect(): void

Opens it.

ConversationItemProps.strings

strings: Strings

The interface texts in the current language.

ConversationItemProps.time

time?: string

“2:41 PM”, “Yesterday”, “Mon”: when the last message was sent.

ConversationItemProps.me

me?: string

My user id (for “You: …” previews and direct-conversation titles).

Components

interface Components

The parts you can replace, passed as components to AgentIM.

Components.Message

Message: ComponentType<MessageProps>

Draws one message.

Components.ConversationItem

ConversationItem: ComponentType<ConversationItemProps>

Draws one conversation list row.

Components.Avatar

Avatar: ComponentType<{ id?: string; name?: string; kind?: string; size?: number }>

Draws an avatar from the id, name and kind (human or agent).

Components.Empty

Empty: ComponentType<{ text: string; hint?: string }>

Draws an empty state (no conversations, no messages).

Components.Steps

Steps?: ComponentType<StepsProps>

Draws an agent’s steps next to its reply (docs/en/design/chat-components.md).

Components.cardBlocks

cardBlocks?: Record<string, ComponentType<CardBlockProps>>

Your own card blocks, by type (x-…, docs/en/design/chat-components.md).

Components.formFields

formFields?: Record<string, ComponentType<FormFieldProps>>

Your own form fields, by type (x-…, docs/en/design/chat-components.md).

Client

type Client = Pick<AgentIMClient, 'connection' | 'conversations' | 'messages' | 'send' | 'edit' | 'recall' | 'retry' | 'discard' | 'feedback' | 'respond' | 'read' | 'call' | 'on'> &

What the hooks need from a client: AgentIMClient, or a fake in tests.

MessagesState

interface MessagesState

What useMessages returns.

MessagesState.messages

messages: Message[]

The messages, oldest first.

MessagesState.hasOlder

hasOlder: boolean

Whether older messages can still be loaded.

MessagesState.olderEnd

olderEnd?: string

start when the beginning is reached, retention when older ones are gone.

MessagesState.loadingOlder

loadingOlder: boolean

Whether older messages are loading now.

MessagesState.loadOlder

loadOlder(): Promise<void>

Loads the next page of older messages.

MessagesState.error

error?: { code: string; message: string }

Why loading older messages failed, if it did.

When

interface When

How dates and times are shown: locale, time zone and “now”.

When.locale

locale?: string

BCP 47 locale; undefined is the user’s own (browser or system).

When.timeZone

timeZone?: string

IANA time zone; undefined is the user’s own.

When.now

now?: number

“Now”, for tests and screenshots.

Row

interface Row

One message row of a laid-out list.

Row.message

message: M

The message.

Row.day

day?: string

A day separator goes above this message.

Row.unread

unread?: boolean

“New messages” goes above this message.

Row.first

first: boolean

First / last of a run from one sender (name and avatar on the first, time on the last).

Row.last

last: boolean

Whether it ends a run of messages from the same sender.

Notice

interface Notice

A line in the timeline that is not a message: a system event, a whisper, progress.

Notice.key

key: string

A stable key for the list.

Notice.seq

seq: number

Goes after the message with this seq (fractions sort between messages).

Notice.content

content: N

What the notice says.

Notice.tone

tone?: 'info' | 'warning' | 'private'

info (default), warning or private (only you can see it).

Item

type Item<M, N> = { row: Row<M>; notice?: undefined } | { notice: Notice<N>; row?: undefined; /** A day separator goes above this notice. */ day?: string }

One entry of a laid-out list: a message row or a notice.

Ended

interface Ended

How this person’s part in a conversation ended, from the client core.

Ended.reason

reason: 'left' | 'removed' | 'dissolved'

left (I left), removed (someone removed me) or dissolved (the conversation was closed).

Ended.by

by?: string

The name of who removed them or closed it (not when it was themselves).

FileType

type FileType = 'pdf' | 'doc' | 'sheet' | 'slides' | 'archive' | 'audio' | 'video' | 'code' | 'image' | 'other'

The icon a file gets, from its name and type (docs/en/design/messaging.md).

Tone

type Tone = 'neutral' | 'success' | 'warning' | 'danger' | 'info'

The colour role of a tone (docs/en/design/chat-components.md); anything else is neutral.

Step

interface Step

One step of an agent’s work (docs/en/design/chat-components.md).

Step.id

id: string

The step’s id within its reply.

Step.title

title: string

What it does, as people read it (“Look up the order”).

Step.state

state: 'pending' | 'running' | 'waiting' | 'done' | 'failed' | 'skipped'

Not started, in progress, waiting (for a person), done, failed or skipped.

Step.detail

detail?: string

A short line under it (“Waiting for approval from Sam”).

Step.data

data?: Record<string, unknown>

The rest of the step’s data (yours to show with your own Steps).

Step.at

at: number

When it was first reported (ms).