Temas y personalización
En esta página
Lección reescrita el 3 de noviembre de 2026. La versión anterior dependía de componentes y opciones que no existen en ChatKit:
ChatProvider,MessageInput, renderizado personalizado de mensajes y hojas de estilo inyectadas. Ahora sigue la guía Theming and customization de OpenAI y los tipos de@openai/chatkit1.9.0; el ejemplo completo se ha verificado mediante compilación de TypeScript. Dos nombres difieren entre la guía y el paquete publicado, y esta lección sigue al paquete:label(noname) para las sugerencias de la pantalla de inicio, yleftActionyrightAction(nocustomButtonLeftycustomButtonRight) para los botones del encabezado. Fuentes: Theming and customization in ChatKit · Referencia deChatKitOptions· ChatKit Studio.
Un único objeto de opciones
Toda la personalización de ChatKit se realiza a través de un único objeto de opciones. En React, se lo pasas a useChatKit({...}); con el componente web, a chatkit.setOptions({...}). La estructura es idéntica en ambos casos, por lo que lo que aprendas aquí se aplica a cualquier integración.
De la arquitectura cubierta en la lección anterior se deriva una consecuencia: ChatKit se renderiza dentro de un iframe, por lo que tu hoja de estilos no puede alcanzarlo. Tus reglas CSS solo se aplican al contenedor: el tamaño y la posición que le das a <ChatKit className="…" />. Todo lo demás se configura mediante opciones. Esto es una buena noticia para el mantenimiento: una actualización de ChatKit no puede romper selectores CSS que no existen.
Para probar opciones sin escribir código, el entorno de pruebas de ChatKit Studio muestra el renderizado en tiempo real.
El tema
El tema controla la apariencia general: esquema de color, color de acento, radio de las esquinas, densidad y tipografía.
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 },
},
});
Cada ajuste tiene un conjunto cerrado de valores, que TypeScript valida por ti:
| Opción | Valores | Efecto |
|---|---|---|
colorScheme | 'light', 'dark' | Tema claro (predeterminado) u oscuro |
color.accent | primary (hex, rgb(), hsl()…), level de 0 a 3 | Color de acento de la interfaz e intensidad de la paleta |
color.grayscale | hue en grados, tint de 0 a 9, shade de −4 a 4 | Tono y sombreado de la paleta de grises |
color.surface | background, foreground | Colores de superficie: fondo y primer plano (texto, iconos) |
radius | 'pill', 'round', 'soft', 'sharp' | Radio de las esquinas para burbujas, botones y campos |
density | 'compact', 'normal', 'spacious' | Espaciado general |
typography | fontFamily, fontFamilyMono, baseSize (14 a 18), fontSources | Fuentes y tamaño base; fontSources carga una fuente web (family, src, weight…) |
Para seguir la preferencia del usuario, elige el esquema al construir las opciones, por ejemplo con window.matchMedia('(prefers-color-scheme: dark)').matches. También se acepta un theme reducido a una cadena, theme: 'dark', cuando solo necesitas establecer el esquema de color.
La pantalla de inicio
Un hilo vacío puede resultar intimidante. La pantalla de inicio lo sustituye por un saludo y sugerencias que muestran al usuario qué puede hacer el asistente:
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 es el texto del botón, prompt es el mensaje que se envía cuando el usuario hace clic e icon es un nombre de la lista de iconos de ChatKit (search, write, calendar, lightbulb…), o un icono de Lucide con el formato 'lucide:name'.
El compositor
El objeto composer configura el texto del marcador de posición, las herramientas que se ofrecen al usuario y los adjuntos:
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'] },
},
},
La herramienta seleccionada del menú se envía al servidor como una preferencia de herramienta para el siguiente turno; debes tenerla en cuenta en tu agente.
Los adjuntos están desactivados por defecto y habilitarlos requiere trabajo en el servidor. Con tu propio servidor, también debes especificar en api cómo se suben los archivos: uploadStrategy: { type: 'direct', uploadUrl: '…' } (la interfaz publica el archivo en tu endpoint) o { type: 'two_phase' } (solicita una URL firmada y luego sube el archivo a tu almacenamiento). En el lado de Python, proporcionas entonces un AttachmentStore. No marques enabled: true hasta que exista esta canalización.
Encabezado, historial y respuestas
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)" },
headermuestra un título fijo (de lo contrario, el título del hilo actual) y hasta dos botones personalizados,leftActionyrightAction, cada uno con un icono de encabezado (settings-cog,home…) y una función.header: { enabled: false }oculta todo el encabezado cuando tu aplicación ya proporciona su propia barra.historyactiva el panel de conversaciones pasadas, con o sin opción de renombrar y eliminar. Desactívalo cuando el concepto de hilo no tenga sentido para tu caso de uso, por ejemplo, para un asistente de soporte sin cuentas de usuario.threadItemActions.feedbackmuestra botones de pulgar arriba y abajo bajo las respuestas. Cada clic llega a tu servidor en el métodoadd_feedbackde tuChatKitServer(thread_id,item_ids,feedbackestablecido en'positive'o'negative'). Esta es la materia prima para tus evaluaciones.retryañade el botón que regenera una respuesta.disclaimermuestra un texto corto en Markdown debajo del compositor.
Idioma
Por defecto, ChatKit usa el idioma del navegador. Si tu aplicación tiene su propia configuración de idioma, impónla con locale: 'en', o una variante regional como 'en-US' o 'en-GB'. Cada solicitud enviada a tu servidor lleva este idioma en la cabecera Accept-Language: úsalo para que el agente responda y para traducir los mensajes de tus herramientas al mismo idioma que la interfaz.
Uniendo todo
Aquí tienes una configuración completa, compilada tal cual 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" />;
}
Puntos clave
- Toda la personalización se realiza a través de un único objeto de opciones, idéntico en React (
useChatKit) y con el componente web (setOptions) - ChatKit se renderiza en un iframe: tu CSS solo estiliza el contenedor; todo lo demás va a través de
theme theme:colorScheme,color.accent,radius,density,typography, con valores cerrados validados por TypeScriptstartScreen(saludo y sugerencias),composer(marcador de posición, herramientas, adjuntos),header,history,threadItemActions,disclaimerylocalecompletan la interfaz- Los adjuntos y los comentarios de los usuarios requieren soporte en el servidor:
uploadStrategyyAttachmentStore, además del métodoadd_feedback