Feature request: Support multiple custom header buttons

[lionnel8]

Current behavior

HeaderOption supports only one button per side (leftAction, rightAction).

type HeaderOption = {
  leftAction?: { icon: HeaderIcon; onClick: () => void };
  rightAction?: { icon: HeaderIcon; onClick: () => void };
};

This is sufficient for simple headers, but it limits flexibility when multiple contextual or custom actions are needed on one side of the header.

Proposed change

Allow arrays instead:

type HeaderOption = {
  leftActions?: { icon: HeaderIcon; onClick: () => void }[];
  rightActions?: { icon: HeaderIcon; onClick: () => void }[];
};

This change would make it possible to create more complex and flexible header configurations without the need for hacks or additional wrapper components.

[tylersmith-openai]

@lionnel8 Would you mind sharing a screenshot of the desired header you're trying to build with multiple icons on either side?

Our general thinking here is that when the complexity needs of your header grow beyond our support, you can create your own custom header by hiding ChatKit's (e.g., header: { enabled: false }).

[lionnel8]

Thanks for your reply @tylersmith-openai!

I’ve also considered this option of disabling the default ChatKit header (header: { enabled: false }), but this unfortunately also seems to mean losing access to the built-in chat history feature.

ChatKit currently doesn’t expose any methods for programmatically opening or hiding the history view. Only the following helpers are available according to the documentation:

focusComposer()
setThreadId(threadId: string | null)
sendUserMessage({ text, reply, attachments, newThread })
setComposerValue({ text, reply, attachments })
fetchUpdates()
sendCustomAction(action, itemId?)

Once the built-in header is disabled, there’s no straightforward way to trigger the history panel from custom UI controls.

My goal is to keep the native ChatKit header and its functionality, but extend it slightly to include two additional buttons: one to toggle fullscreen mode and another to close the chat window, as illustrated in the screenshot below, which shows my current custom implementation of the chat UI.

[tylersmith-openai]

ChatKit currently doesn’t expose any methods for programmatically opening or hiding the history view. Only the following helpers are available according to the documentation:

Ah, great point! We should definitely expose this.

My goal is to keep the native ChatKit header and its functionality, but extend it slightly to include two additional buttons: one to toggle fullscreen mode and another to close the chat window, as illustrated in the screenshot below, which shows my current custom implementation of the chat UI.

Makes perfect sense, thank you!

I'll circle with the team and follow-up when I have an update to share. I suspect supporting imperative methods for history will be the first step, but we'll also think through how more flexibility in the custom actions can be supported.

[lucianogorza]

Hi @lionnel8! Could you explain how you added a logo to the welcome message? Thank you.

[tylersmith-openai]

@lucianogorza That screenshot is not of a ChatKit, to be clear.

We definitely want to add more expression to the Start Screen soon, though!

[lucianogorza]

@tylersmith-openai Thank you! Although it already includes some customization settings, it would be fantastic to have more options to better adapt it to a brand.