Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Teman och anpassning

Lektion 18 av 25 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Ett enda optionsobjekt
  2. Temat
  3. Startskärmen
  4. Kompositören
  5. Sidhuvud, historik och svar
  6. Språk
  7. Sätta ihop allt
  8. Viktiga punkter

Lektionen omskriven den 3 november 2026. Den tidigare versionen förlitade sig på komponenter och alternativ som inte finns i ChatKit: ChatProvider, MessageInput, anpassad meddelanderendering och injicerade stilmallar. Den följer nu OpenAIs guide Theming and customization och typerna från @openai/chatkit 1.9.0; hela exemplet har verifierats via TypeScript-kompilering. Två namn skiljer sig mellan guiden och det publicerade paketet, och denna lektion följer paketet: label (inte name) för förslag på startskärmen, samt leftAction och rightAction (inte customButtonLeft och customButtonRight) för knappar i sidhuvudet. Källor: Theming and customization in ChatKit · ChatKitOptions-referens · ChatKit Studio.

Ett enda optionsobjekt

All anpassning av ChatKit sker genom ett enda optionsobjekt. I React skickar du det till useChatKit({...}); med webbkompontenten skickar du det till chatkit.setOptions({...}). Strukturen är identisk i båda fallen, så det du lär dig här gäller för varje integration.

En konsekvens följer av arkitekturen som täcktes i föregående lektion: ChatKit renderar inuti en iframe, så din stilmall når inte dit. Dina CSS-regler gäller endast för containern – storleken och positionen du ger <ChatKit className="…" />. Allt annat konfigureras via options. Detta är goda nyheter för underhållet: en uppdatering av ChatKit kan inte bryta CSS-selektorer som inte finns.

För att testa options utan att skriva kod visar ChatKit Studio playground rendering i realtid.

Temat

Temat styr det övergripande utseendet: färgschema, accentfärg, hörnradie, densitet och typografi.

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 },
  },
});

Varje inställning har en sluten uppsättning värden, vilket TypeScript validerar åt dig:

AlternativVärdenEffekt
colorScheme'light', 'dark'Ljust (standard) eller mörkt tema
color.accentprimary (hex, rgb(), hsl()…), level från 0 till 3Gränssnittets accentfärg och palettens intensitet
color.grayscalehue i grader, tint från 0 till 9, shade från −4 till 4Nyans och skugga för den grå paletten
color.surfacebackground, foregroundYtfärger: bakgrund och förgrund (text, ikoner)
radius'pill', 'round', 'soft', 'sharp'Hörnradie för bubblor, knappar och fält
density'compact', 'normal', 'spacious'Övergripande avstånd
typographyfontFamily, fontFamilyMono, baseSize (14 till 18), fontSourcesTypsnitt och basstorlek; fontSources laddar ett webbtypsnitt (family, src, weight…)

För att följa användarens preferens, välj schemat när du bygger options, till exempel med window.matchMedia('(prefers-color-scheme: dark)').matches. Ett theme reducerat till en sträng, theme: 'dark', accepteras också när du bara behöver ställa in färgschemat.

Startskärmen

En tom tråd kan kännas skrämmande. Startskärmen ersätter den med en hälsning och förslag som visar användaren vad assistenten kan göra:

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 är knapptexten, prompt är meddelandet som skickas när användaren klickar, och icon är ett namn från ChatKits ikonlista (search, write, calendar, lightbulb…), eller en Lucide-ikon på formen 'lucide:name'.

Kompositören

Objektet composer konfigurerar platshållartext, verktyg som erbjuds användaren och bilagor:

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 fil
    accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
  },
},

Verktyget som väljs från menyn skickas till servern som en verktygspreferens för nästa tur; du måste ta hänsyn till detta i din agent.

Bilagor är inaktiverade som standard, och att aktivera dem kräver arbete på serversidan. Med din egen server måste du också ange i api hur filer laddas upp: uploadStrategy: { type: 'direct', uploadUrl: '…' } (gränssnittet postar filen till din endpoint) eller { type: 'two_phase' } (det begär en signerad URL och laddar sedan upp filen till ditt lagring). På Python-sidan tillhandahåller du sedan en AttachmentStore. Kryssa inte i enabled: true förrän denna pipeline finns.

Sidhuvud, historik och svar

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 visar en fast titel (annars den aktuella trådtiteln) och upp till två anpassade knappar, leftAction och rightAction, var och en med en sidhuvudsikon (settings-cog, home…) och en funktion. header: { enabled: false } döljer hela sidhuvudet när din applikation redan tillhandahåller sin egen menylist.
  • history aktiverar panelen för tidigare konversationer, med eller utan möjlighet att byta namn och radera. Inaktivera detta när begreppet tråd inte ger mening för ditt användningsfall, till exempel för en supportassistent utan användarkonton.
  • threadItemActions.feedback visar tumme upp- och tumme ner-knappar under svar. Varje klick når din server i metoden add_feedback i din ChatKitServer (thread_id, item_ids, feedback satt till 'positive' eller 'negative'). Detta är råmaterialet för dina utvärderingar. retry lägger till knappen som genererar om ett svar.
  • disclaimer visar en kort Markdown-text under kompositören.

Språk

Som standard använder ChatKit webbläsarens språk. Om din applikation har sin egen språkinställning, tvinga fram den med locale: 'en', eller en regional variant som 'en-US' eller 'en-GB'. Varje begäran som skickas till din server bär med sig detta språk i headern Accept-Language: använd det för att få agenten att svara och för att översätta dina verktygsmeddelanden till samma språk som gränssnittet.

Sätta ihop allt

Här är en komplett konfiguration, kompilerad i befintligt skick med @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" />;
}

Viktiga punkter

  • All anpassning sker genom ett enda optionsobjekt, identiskt i React (useChatKit) och med webbkompontenten (setOptions)
  • ChatKit renderar i en iframe: din CSS stylar endast containern; allt annat går via theme
  • theme: colorScheme, color.accent, radius, density, typography, med slutna värden validerade av TypeScript
  • startScreen (hälsning och förslag), composer (platshållare, verktyg, bilagor), header, history, threadItemActions, disclaimer och locale kompletterar gränssnittet
  • Bilagor och användarfeedback kräver stöd på serversidan: uploadStrategy och AttachmentStore, plus metoden add_feedback