How to Custom Brand ONLYOFFICE Docs with Your Logo and Colors

The shortest answer: use Docs API branding for the logo, and a custom interface theme for the colors

If your goal is to make the ONLYOFFICE Docs editor look like part of your own product, the cleanest setup is a two-layer customization: configure editorConfig.customization.logo in the Docs API integration for the header logo, then add a custom theme JSON file on the Document Server for the editor colors. These are separate mechanisms, and they have different availability rules.

As verified against ONLYOFFICE documentation on October 7, 2026, the editor-header logo parameter is available only for ONLYOFFICE Docs Developer. The official API specifies 300×20 images for image, imageDark, and imageLight, with a recommended logo height of 20 pixels. Custom interface themes, meanwhile, have been supported since ONLYOFFICE Docs v7.0 and are installed as JSON theme files on the Document Server. The current official reference is the ONLYOFFICE Docs standard branding documentation, and the theme file workflow is documented in Changing interface themes in ONLYOFFICE Docs.

This approach fits teams that embed ONLYOFFICE Docs into their own web application and control the Document Server. It is not the same as changing a DocSpace or Workspace portal theme. If your target is the surrounding portal rather than the editor itself, use that product’s branding settings instead.

Step 1: confirm what you actually need to brand

Before editing files, separate the branding surface into three questions. Do you only need a logo in the editor header? Do you also want brand colors throughout toolbars, buttons, text, borders, and panels? Or do you need a deeper white-label experience that changes additional interface elements?

• Header logo: use editorConfig.customization.logo. ONLYOFFICE marks this parameter as Developer-only.
• Interface colors: install a custom theme JSON on the Document Server. This is the right mechanism for brand colors.
• Deeper white-label controls: check the extended white label documentation. ONLYOFFICE states that those parameters require the extended white label license for Docs Developer.

This distinction matters because changing a theme file will not automatically replace the header logo, and setting the logo object will not recolor the rest of the editor.

Step 2: prepare logo files for light and dark headers

Prepara un logotipo ancho y sencillo que se mantenga legible con una altura de encabezado de 20 píxeles. La documentación de la API especifica un tamaño de imagen de 300 × 20 para las variantes estándar de imágenes de encabezado. Utiliza diseños distintos para fondos oscuros y claros cuando tu marca pierda contraste. Por ejemplo, un logotipo tipográfico azul marino oscuro puede funcionar bien en un encabezado claro, pero desaparecer en un tema oscuro; una variante blanca o clara soluciona este problema.

Aloje las imágenes en URL HTTPS estables que el editor pueda cargar. Evite las URL firmadas de corta duración si el logotipo debe estar disponible de forma constante. Pruebe también los recursos a través de la misma ruta de red y la misma política de seguridad del navegador que utilizan los usuarios reales.

Paso 3: agregue el logotipo a la configuración de su API de Docs.

const config = {
  editorConfig: {
    customization: {
      logo: {
        image: "https://app.example.com/branding/logo.png",
        imageDark: "https://app.example.com/branding/logo-dark.png",
        imageLight: "https://app.example.com/branding/logo-light.png",
        url: "https://www.example.com",
        visible: true
      }
    }
  }
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

imagees el logotipo común del modo de trabajo. imageDarkes para un encabezado oscuro o de color, y imageLightes para un encabezado claro como el tema Gris. urlcontrola a dónde va un clic en el logotipo; configúrelo como una cadena vacía o nullsi el logotipo no debe ser clicable. visiblecontrola si el logotipo se muestra.

Paso 4: verificar el logotipo tanto en condiciones de luz como de oscuridad.

Abra un documento real mediante su integración y compruebe el encabezado con el zoom normal del navegador. Un resultado satisfactorio no se limita a que el archivo se haya cargado correctamente. El logotipo debe ser nítido, estar centrado verticalmente, ser legible con la altura compacta del encabezado y no presentar cuadros de fondo inesperados. Compruebe también que al hacer clic se comporta como se espera.

A continuación, cambia a una interfaz oscura y repite la comprobación. Si el logotipo presenta poco contraste, utiliza un imageDarkrecurso gráfico específico en lugar de intentar que un solo gráfico funcione en todas partes.

Paso 5: crea un JSON con un tema de color personalizado.

Para los colores de la interfaz, cree un archivo de tema que idcomience con theme-. ONLYOFFICE documentos lighty darkcomo tipos de tema válidos, y admite colores en notación hexadecimal o RGBA. No lo confunda con un esquema de color de documento: este JSON cambia la apariencia del editor, no los colores del tema almacenados en un archivo DOCX, XLSX o PPTX.

{
  "name": "Northstar Light",
  "id": "theme-northstar-light",
  "type": "light",
  "colors": {
    "toolbar-header-document": "#1E3A8A",
    "toolbar-header-spreadsheet": "#166534",
    "toolbar-header-presentation": "#B45309",
    "background-normal": "#FFFFFF",
    "background-accent-button": "#1E3A8A",
    "text-normal": "#1F2937",
    "icon-normal": "#374151"
  }
}

Los valores anteriores son una paleta de ejemplo, no un tema predefinido de ONLYOFFICE. Los nombres de los parámetros corresponden a variables del tema documentadas. En producción, comience con un conjunto pequeño de valores de alto impacto, previsualice el resultado y amplíelo solo cuando sea necesario. Esto facilita la detección de contrastes deficientes o estados inconsistentes.

Paso 6: coloque el archivo de tema en el directorio de temas del servidor de documentos.

ONLYOFFICE documenta estas ubicaciones para los archivos de temas personalizados:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: copie el JSON en la misma ruta dentro del contenedor Docs.

sudo docker cp northstar-theme.json onlyoffice:/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes/

Sustituye esto onlyofficepor el nombre o ID real de tu contenedor. Si tu implementación se reconstruye con frecuencia, no confíes en una copia única como única fuente de información. Integra el tema en tu proceso de implementación, personalización de imágenes u otro mecanismo persistente adecuado a tu entorno para que las actualizaciones y los reemplazos de contenedores no lo eliminen silenciosamente.

Paso 7: actualiza, espera a que se cargue la caché y selecciona el tema personalizado.

La guía oficial indica que la caché del servidor para la solicitud del tema tiene una duración de cinco minutos. Tras colocar el archivo, espere ese tiempo y actualice el editor. En algunos casos, ONLYOFFICE también recomienda reiniciar los servicios y borrar la caché si el tema no aparece.

Una vez cargado, el tema debería aparecer en la lista de temas de la interfaz en la configuración avanzada. Selecciónelo e inspeccione más que solo el encabezado. Revise los menús, los cuadros de diálogo, las pestañas seleccionadas, los estados al pasar el cursor, los controles deshabilitados, los íconos, las insignias de notificación y el contraste del texto.

Paso 8: validar la marca finalizada como un sistema, no solo como una captura de pantalla.

Una buena marca personalizada debería resistir el uso normal del editor. Abra un documento, una hoja de cálculo, una presentación y un PDF si estos editores están disponibles. Pruebe los cuadros de diálogo y los controles de colaboración más comunes. Verifique las condiciones de luz y oscuridad si ofrece ambas. Compruebe el enfoque del teclado, los estados deshabilitados, el contraste al pasar el cursor y los nombres de archivo largos. Un color que se vea atractivo en el encabezado puede dificultar la lectura de una pestaña seleccionada o del texto secundario.

Cómo saber si la personalización funciona.

Se puede considerar que la implementación ha sido exitosa cuando el logotipo configurado aparece de forma consistente, la variante correcta del logotipo permanece legible en el encabezado activo, el tema personalizado aparece en el selector de temas, los colores de la marca se muestran sin que se rompa el contraste del texto o los iconos, y la experiencia sigue siendo utilizable en todos los tipos de editor que sus usuarios realmente abren.

Si el logotipo no cambia aunque el objeto de configuración se esté pasando correctamente, primero confirme la edición y la licencia, ya que la documentación de la API indica que el parámetro del logotipo es exclusivo para desarrolladores de la documentación. Si el tema de color no aparece, verifique el ID y la sintaxis JSON, la ubicación del archivo, la persistencia del contenedor, la sincronización de la caché y el estado del servicio. Si un tema se carga pero tiene un aspecto incorrecto, reduzca la personalización a un conjunto menor de variables documentadas y agregue los colores de forma incremental.

Límites y errores comunes

Personalizar el editor no es lo mismo que personalizar DocSpace o Workspace.

ONLYOFFICE cuenta con superficies de personalización independientes. Esta guía se centra específicamente en la personalización de la marca del editor de documentos de ONLYOFFICE. Los controles de personalización del portal, los nombres de los inquilinos, los iconos del portal y la navegación circundante pertenecen a la configuración de DocSpace o Workspace, no al logotipo del encabezado de la API de Docs.

Un esquema de colores de un documento no es un tema de interfaz.

Los esquemas de color de los documentos afectan al contenido, como texto, tablas, gráficos y formas. Un tema de interfaz personalizado controla los elementos de la interfaz de usuario del editor, como barras de herramientas, paneles, botones, iconos, bordes y etiquetas. Elija el mecanismo que mejor se adapte a la superficie que desea modificar.

No dé por sentado que todos los controles de marca blanca están incluidos con la marca estándar.

ONLYOFFICE distingue entre la personalización estándar y los parámetros de marca blanca ampliados. Si necesita un mayor control sobre elementos como las fuentes de la interfaz, la visibilidad del diseño o los elementos relacionados con la sección "Acerca de", consulte los requisitos de licencia vigentes en la documentación oficial de marca blanca antes de planificar la implementación.

Lista de verificación para la implementación práctica

• Confirme con el desarrollador de ONLYOFFICE Docs si necesita la personalización del logotipo del encabezado que se describe aquí.
• Crea elementos gráficos de logotipos de 300×20, incluyendo variantes claras y oscuras donde el contraste lo requiera.
• Configurar editorConfig.customization.logoen la capa de integración.
• Crea un JSON de tema personalizado válido con un ID que comience con theme-.
• Coloque el archivo de tema en el directorio de temas del servidor de documentos documentado.
• Para implementaciones en Docker o inmutables, asegúrese de que la instalación del tema sea repetible y persistente.
• Espere el tiempo de espera de la caché documentada, luego actualice la página y seleccione el tema.
• Pruebe el contraste, los estados, los tipos de editor y las condiciones de luz y oscuridad antes de su implementación generalizada.

Al mantener separados conceptualmente la identidad visual, la interfaz y los controles de marca blanca extendidos, la personalización de ONLYOFFICE Docs resulta mucho más sencilla y predecible. Comience con el cambio más pequeño que logre la coherencia con la marca deseada, verifíquelo en condiciones reales de edición y, solo entonces, amplíe el tema.

Referencias oficiales

• API de documentos de ONLYOFFICE: Personalización – Imagen de marca estándar
• Centro de ayuda de ONLYOFFICE: Cómo cambiar los temas de la interfaz en ONLYOFFICE Docs
• API de documentos de ONLYOFFICE: Personalización – Marca blanca