Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Thema's en aanpassingen

Les 18 van 25 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Eén enkel optiesobject
  2. Het thema
  3. Het startscherm
  4. De composer
  5. Koptekst, geschiedenis en antwoorden
  6. Taal
  7. Alles samenvoegen
  8. Belangrijkste punten

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/chatkit 1.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 (niet name) voor suggesties op het startscherm, en leftAction en rightAction (niet customButtonLeft en customButtonRight) voor knoppen in de koptekst. Bronnen: Theming and customization in ChatKit · ChatKitOptions referentie · 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:

OptieWaardenEffect
colorScheme'light', 'dark'Licht (standaard) of donker thema
color.accentprimary (hex, rgb(), hsl()…), level van 0 tot 3Accentkleur van de interface en intensiteit van het palet
color.grayscalehue in graden, tint van 0 tot 9, shade van −4 tot 4Tint en schaduw van het grijspalet
color.surfacebackground, foregroundOppervlakkleuren: 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
typographyfontFamily, fontFamilyMono, baseSize (14 tot 18), fontSourcesLettertypen 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)" },
  • header toont een vaste titel (anders de huidige threadtitel) en maximaal twee aangepaste knoppen, leftAction en rightAction, 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.
  • history schakelt 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.feedback toont duimen-omhoog en -omlaag-knoppen onder antwoorden. Elke klik komt aan op uw server in de add_feedback-methode van uw ChatKitServer (thread_id, item_ids, feedback ingesteld op 'positive' of 'negative'). Dit is de grondstof voor uw evaluaties. retry voegt de knop toe die een antwoord opnieuw genereert.
  • disclaimer toont 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 gevalideerd
  • startScreen (begroeting en suggesties), composer (placeholder, tools, bijlagen), header, history, threadItemActions, disclaimer en locale vervolledigen de interface
  • Bijlagen en gebruikersfeedback vereisen ondersteuning aan de serverkant: uploadStrategy en AttachmentStore, plus de add_feedback-methode