Thema's en aanpassingen
Op deze pagina
Les herschreven op 3 november 2026. De vorige versie vertrouwde op componenten en opties die niet bestaan in ChatKit:
ChatProvider,MessageInput, aangepaste berichtweergave en geïnjecteerde stylesheets. Deze les volgt nu de OpenAI-gids Theming and customization en de types uit@openai/chatkit1.9.0; het volledige voorbeeld is geverifieerd via TypeScript-compilatie. Twee namen verschillen tussen de gids en het gepubliceerde pakket, en deze les volgt het pakket:label(nietname) voor suggesties op het startscherm, enleftActionenrightAction(nietcustomButtonLeftencustomButtonRight) voor knoppen in de koptekst. Bronnen: Theming and customization in ChatKit ·ChatKitOptionsreferentie · ChatKit Studio.
Eén enkel optiesobject
Alle aanpassingen van ChatKit gebeuren via één enkel optiesobject. In React geeft u dit door aan useChatKit({...}); bij de webcomponent aan chatkit.setOptions({...}). De structuur is in beide gevallen identiek, dus wat u hier leert, is van toepassing op elke integratie.
Een gevolg van de architectuur die in de vorige les aan bod kwam, is dat ChatKit binnen een iframe wordt weergegeven, waardoor uw stylesheet er geen toegang toe heeft. Uw CSS-regels zijn alleen van toepassing op de container—de grootte en positie die u meegeeft aan <ChatKit className="…" />. Alles verder configureert u via opties. Dit is goed nieuws voor het onderhoud: een update van ChatKit kan geen CSS-selectors breken die niet bestaan.
Om opties uit te proberen zonder code te schrijven, toont de ChatKit Studio playground de live-weergave.
Het thema
Het thema bepaalt de algemene uitstraling: kleurenschema, accentkleur, straal van de hoeken, dichtheid en typografie.
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
theme: {
colorScheme: 'dark',
color: {
accent: { primary: '#2D8CFF', level: 2 },
},
radius: 'round',
density: 'compact',
typography: { fontFamily: "'Inter', sans-serif", baseSize: 16 },
},
});
Elke instelling heeft een gesloten reeks waarden, die TypeScript voor u valideert:
| Optie | Waarden | Effect |
|---|---|---|
colorScheme | 'light', 'dark' | Licht (standaard) of donker thema |
color.accent | primary (hex, rgb(), hsl()…), level van 0 tot 3 | Accentkleur van de interface en intensiteit van het palet |
color.grayscale | hue in graden, tint van 0 tot 9, shade van −4 tot 4 | Tint en schaduw van het grijspalet |
color.surface | background, foreground | Oppervlakkleuren: achtergrond en voorgrond (tekst, iconen) |
radius | 'pill', 'round', 'soft', 'sharp' | Straal van de hoeken voor bubbels, knoppen en velden |
density | 'compact', 'normal', 'spacious' | Algemene tussenruimte |
typography | fontFamily, fontFamilyMono, baseSize (14 tot 18), fontSources | Lettertypen en basisgrootte; fontSources laadt een webfont (family, src, weight…) |
Om de voorkeur van de gebruiker te volgen, kiest u het schema bij het bouwen van de opties, bijvoorbeeld met window.matchMedia('(prefers-color-scheme: dark)').matches. Een theme gereduceerd tot een string, theme: 'dark', wordt ook geaccepteerd wanneer u alleen het kleurenschema hoeft in te stellen.
Het startscherm
Een lege thread kan intimiderend overkomen. Het startscherm vervangt deze door een begroeting en suggesties die de gebruiker laten zien wat de assistent kan doen:
startScreen: {
greeting: 'Hello! How can I help you?',
prompts: [
{ label: 'Track an order', prompt: 'Where is my latest order?', icon: 'search' },
{ label: 'Open a ticket', prompt: 'I would like to report an issue.', icon: 'write' },
],
},
label is de knoptekst, prompt is het bericht dat wordt verzonden wanneer de gebruiker klikt, en icon is een naam uit de ChatKit-iconenlijst (search, write, calendar, lightbulb…), of een Lucide-icoon in de vorm 'lucide:name'.
De composer
Het object composer configureert de placeholdertekst, de tools die aan de gebruiker worden aangeboden en bijlagen:
composer: {
placeholder: 'Ask a question about your order…',
tools: [
{ id: 'order-search', label: 'Search order', icon: 'search', pinned: true },
],
attachments: {
enabled: true,
maxCount: 3,
maxSize: 20 * 1024 * 1024, // 20 MB per bestand
accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
},
},
De tool die uit het menu wordt geselecteerd, wordt naar de server verzonden als een toolvoorkeur voor de volgende beurt; u moet hier rekening mee houden in uw agent.
Bijlagen zijn standaard uitgeschakeld en het inschakelen ervan vereist werk aan de serverkant. Met uw eigen server moet u ook in api specificeren hoe bestanden worden geüpload: uploadStrategy: { type: 'direct', uploadUrl: '…' } (de interface post het bestand naar uw endpoint) of { type: 'two_phase' } (het vraagt een ondertekende URL aan en uploadt het bestand vervolgens naar uw opslag). Aan de Python-kant levert u vervolgens een AttachmentStore. Vink enabled: true pas aan als deze pipeline bestaat.
Koptekst, geschiedenis en antwoorden
header: {
title: { text: 'Order Assistant' },
leftAction: { icon: 'settings-cog', onClick: () => openSettings() },
},
history: { enabled: true, showRename: true, showDelete: false },
threadItemActions: { feedback: true, retry: true },
disclaimer: { text: "Responses may contain errors. [Our terms](/terms)" },
headertoont een vaste titel (anders de huidige threadtitel) en maximaal twee aangepaste knoppen,leftActionenrightAction, elk met een kopteksticoon (settings-cog,home…) en een functie.header: { enabled: false }verbergt de volledige koptekst wanneer uw applicatie al zijn eigen balk biedt.historyschakelt het paneel met eerdere gesprekken in, met of zonder hernoemen en verwijderen. Schakel dit uit wanneer het concept van een thread geen zin heeft voor uw use-case, bijvoorbeeld voor een supportassistent zonder gebruikersaccounts.threadItemActions.feedbacktoont duimen-omhoog en -omlaag-knoppen onder antwoorden. Elke klik komt aan op uw server in deadd_feedback-methode van uwChatKitServer(thread_id,item_ids,feedbackingesteld op'positive'of'negative'). Dit is de grondstof voor uw evaluaties.retryvoegt de knop toe die een antwoord opnieuw genereert.disclaimertoont een korte Markdown-tekst onder de composer.
Taal
Standaard gebruikt ChatKit de taal van de browser. Als uw applicatie zijn eigen taalinstelling heeft, forceert u deze met locale: 'en', of een regionale variant zoals 'en-US' of 'en-GB'. Elk verzoek dat naar uw server wordt verzonden, draagt deze taal mee in de Accept-Language-header: gebruik deze om de agent te laten antwoorden en om uw toolberichten in dezelfde taal als de interface te vertalen.
Alles samenvoegen
Hier is een volledige configuratie, zoals deze is gecompileerd met @openai/chatkit-react 1.6.1:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function OrderAssistant({ openSettings }: { openSettings: () => void }) {
const dark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
locale: 'en',
theme: {
colorScheme: dark ? 'dark' : 'light',
color: { accent: { primary: '#2D8CFF', level: 2 } },
radius: 'round',
density: 'normal',
},
startScreen: {
greeting: 'Hello! How can I help you?',
prompts: [
{ label: 'Track an order', prompt: 'Where is my latest order?', icon: 'search' },
{ label: 'Open a ticket', prompt: 'I would like to report an issue.', icon: 'write' },
],
},
composer: { placeholder: 'Ask a question about your order…' },
header: {
title: { text: 'Order Assistant' },
leftAction: { icon: 'settings-cog', onClick: openSettings },
},
history: { enabled: true, showRename: true, showDelete: false },
threadItemActions: { feedback: true, retry: true },
});
return <ChatKit control={control} className="h-[640px] w-full max-w-md" />;
}
Belangrijkste punten
- Alle aanpassingen gebeuren via één enkel optiesobject, identiek in React (
useChatKit) en met de webcomponent (setOptions) - ChatKit wordt weergegeven in een iframe: uw CSS stylet alleen de container; alles verder gaat via
theme theme:colorScheme,color.accent,radius,density,typography, met gesloten waarden die door TypeScript worden gevalideerdstartScreen(begroeting en suggesties),composer(placeholder, tools, bijlagen),header,history,threadItemActions,disclaimerenlocalevervolledigen de interface- Bijlagen en gebruikersfeedback vereisen ondersteuning aan de serverkant:
uploadStrategyenAttachmentStore, plus deadd_feedback-methode