Temi e personalizzazione
In questa pagina
Lezione riscritta il 3 novembre 2026. La versione precedente si basava su componenti e opzioni inesistenti in ChatKit:
ChatProvider,MessageInput, rendering personalizzato dei messaggi e fogli di stile iniettati. Ora segue la guida Theming and customization di OpenAI e i tipi di@openai/chatkit1.9.0; l’esempio completo è stato verificato tramite compilazione TypeScript. Due nomi differiscono tra la guida e il pacchetto pubblicato: questa lezione segue il pacchetto, usandolabel(nonname) per i suggerimenti della schermata iniziale, eleftActionerightAction(noncustomButtonLeftecustomButtonRight) per i pulsanti dell’intestazione. Fonti: Theming and customization in ChatKit · RiferimentoChatKitOptions· ChatKit Studio.
Un unico oggetto di opzioni
Tutta la personalizzazione di ChatKit avviene tramite un singolo oggetto di opzioni. In React, lo passi a useChatKit({...}); con il componente web, a chatkit.setOptions({...}). La struttura è identica in entrambi i casi, quindi ciò che impari qui si applica a ogni integrazione.
Una conseguenza deriva dall’architettura trattata nella lezione precedente: ChatKit esegue il rendering all’interno di un iframe, quindi il tuo foglio di stile non può raggiungerlo. Le tue regole CSS si applicano solo al contenitore: le dimensioni e la posizione che assegni a <ChatKit className="…" />. Tutto il resto si configura tramite le opzioni. Questa è una buona notizia per la manutenzione: un aggiornamento di ChatKit non può rompere selettori CSS che non esistono.
Per provare le opzioni senza scrivere codice, il playground di ChatKit Studio mostra il rendering in tempo reale.
Il tema
Il tema controlla l’aspetto generale: schema colori, colore di accento, raggio degli angoli, densità e tipografia.
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 },
},
});
Ogni impostazione ha un insieme chiuso di valori, che TypeScript valida per te:
| Opzione | Valori | Effetto |
|---|---|---|
colorScheme | 'light', 'dark' | Tema chiaro (predefinito) o scuro |
color.accent | primary (hex, rgb(), hsl()…), level da 0 a 3 | Colore di accento dell’interfaccia e intensità della tavolozza |
color.grayscale | hue in gradi, tint da 0 a 9, shade da −4 a 4 | Tonalità e sfumatura della tavolozza dei grigi |
color.surface | background, foreground | Colori di superficie: sfondo e primo piano (testo, icone) |
radius | 'pill', 'round', 'soft', 'sharp' | Raggio degli angoli per bolle, pulsanti e campi |
density | 'compact', 'normal', 'spacious' | Spaziatura generale |
typography | fontFamily, fontFamilyMono, baseSize (da 14 a 18), fontSources | Font e dimensione base; fontSources carica un font web (family, src, weight…) |
Per seguire la preferenza dell’utente, scegli lo schema durante la costruzione delle opzioni, ad esempio con window.matchMedia('(prefers-color-scheme: dark)').matches. È accettato anche un theme ridotto a una stringa, theme: 'dark', quando devi solo impostare lo schema colori.
La schermata iniziale
Una conversazione vuota può risultare intimidatoria. La schermata iniziale la sostituisce con un saluto e suggerimenti che mostrano all’utente cosa può fare l’assistente:
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 è il testo del pulsante, prompt è il messaggio inviato quando l’utente fa clic e icon è un nome dalla lista delle icone di ChatKit (search, write, calendar, lightbulb…), oppure un’icona Lucide nella forma 'lucide:name'.
Il compositore
L’oggetto composer configura il testo segnaposto, gli strumenti offerti all’utente e gli allegati:
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 file
accept: { 'application/pdf': ['.pdf'], 'image/*': ['.png', '.jpg'] },
},
},
Lo strumento selezionato dal menu viene inviato al server come preferenza di strumento per il turno successivo; devi tenerne conto nel tuo agente.
Gli allegati sono disabilitati di default e abilitarli richiede lavoro lato server. Con il tuo server, devi anche specificare in api come vengono caricati i file: uploadStrategy: { type: 'direct', uploadUrl: '…' } (l’interfaccia invia il file al tuo endpoint) oppure { type: 'two_phase' } (richiede un URL firmato, poi carica il file nel tuo storage). Sul lato Python, fornisci quindi un AttachmentStore. Non impostare enabled: true finché questa pipeline non esiste.
Intestazione, cronologia e risposte
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)" },
headervisualizza un titolo fisso (altrimenti il titolo della conversazione corrente) e fino a due pulsanti personalizzati,leftActionerightAction, ognuno con un’icona nell’intestazione (settings-cog,home…) e una funzione.header: { enabled: false }nasconde l’intera intestazione quando la tua applicazione fornisce già la propria barra.historyabilita il pannello delle conversazioni passate, con o senza possibilità di rinominare ed eliminare. Disabilitalo quando il concetto di conversazione non ha senso per il tuo caso d’uso, ad esempio per un assistente di supporto senza account utente.threadItemActions.feedbackvisualizza i pulsanti pollice in su e in giù sotto le risposte. Ogni clic arriva al tuo server nel metodoadd_feedbackdel tuoChatKitServer(thread_id,item_ids,feedbackimpostato su'positive'o'negative'). Questa è la materia prima per le tue valutazioni.retryaggiunge il pulsante che rigenera una risposta.disclaimervisualizza un breve testo Markdown sotto il compositore.
Lingua
Di default, ChatKit usa la lingua del browser. Se la tua applicazione ha una propria impostazione linguistica, imponila con locale: 'en', o una variante regionale come 'en-US' o 'en-GB'. Ogni richiesta inviata al tuo server porta questa lingua nell’intestazione Accept-Language: usala per far rispondere l’agente e per tradurre i messaggi dei tuoi strumenti nella stessa lingua dell’interfaccia.
Mettere tutto insieme
Ecco una configurazione completa, compilata così com’è con @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" />;
}
Punti chiave
- Tutta la personalizzazione avviene tramite un unico oggetto di opzioni, identico in React (
useChatKit) e con il componente web (setOptions) - ChatKit esegue il rendering in un iframe: il tuo CSS stila solo il contenitore; tutto il resto passa attraverso
theme theme:colorScheme,color.accent,radius,density,typography, con valori chiusi validati da TypeScriptstartScreen(saluto e suggerimenti),composer(segnaposto, strumenti, allegati),header,history,threadItemActions,disclaimerelocalecompletano l’interfaccia- Allegati e feedback utente richiedono supporto lato server:
uploadStrategyeAttachmentStore, oltre al metodoadd_feedback