Ir al contenido principal
Español— Elegir un idioma
Menú

Temas y personalización

Lección 18 de 25 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Un único objeto de opciones
  2. El tema
  3. La pantalla de inicio
  4. El compositor
  5. Encabezado, historial y respuestas
  6. Idioma
  7. Uniendo todo
  8. Puntos clave

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/chatkit 1.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 (no name) para las sugerencias de la pantalla de inicio, y leftAction y rightAction (no customButtonLeft y customButtonRight) para los botones del encabezado. Fuentes: Theming and customization in ChatKit · Referencia de ChatKitOptions · 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ónValoresEfecto
colorScheme'light', 'dark'Tema claro (predeterminado) u oscuro
color.accentprimary (hex, rgb(), hsl()…), level de 0 a 3Color de acento de la interfaz e intensidad de la paleta
color.grayscalehue en grados, tint de 0 a 9, shade de −4 a 4Tono y sombreado de la paleta de grises
color.surfacebackground, foregroundColores 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
typographyfontFamily, fontFamilyMono, baseSize (14 a 18), fontSourcesFuentes 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)" },
  • header muestra un título fijo (de lo contrario, el título del hilo actual) y hasta dos botones personalizados, leftAction y rightAction, 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.
  • history activa 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.feedback muestra botones de pulgar arriba y abajo bajo las respuestas. Cada clic llega a tu servidor en el método add_feedback de tu ChatKitServer (thread_id, item_ids, feedback establecido en 'positive' o 'negative'). Esta es la materia prima para tus evaluaciones. retry añade el botón que regenera una respuesta.
  • disclaimer muestra 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 TypeScript
  • startScreen (saludo y sugerencias), composer (marcador de posición, herramientas, adjuntos), header, history, threadItemActions, disclaimer y locale completan la interfaz
  • Los adjuntos y los comentarios de los usuarios requieren soporte en el servidor: uploadStrategy y AttachmentStore, además del método add_feedback