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

Подготовьте широкий, простой логотип, который останется читаемым при высоте заголовка в 20 пикселей. В документации API указан размер изображения 300×20 для стандартных вариантов изображений заголовка. Используйте отдельные изображения для темного и светлого фона, если ваш фирменный знак потеряет контраст. Например, темно-синий текстовый логотип может хорошо смотреться на светлом заголовке, но исчезнет на темном фоне; белый или светлый вариант решит эту проблему.

Размещайте изображения по стабильным HTTPS-адресам, которые редактор сможет загрузить. Избегайте кратковременных подписанных URL-адресов, если логотип должен быть постоянно доступен. Также тестируйте ресурсы, используя тот же сетевой путь и политику безопасности браузера, что и реальные пользователи.

Шаг 3: добавьте логотип в конфигурацию API для работы с документами.

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

image— это стандартный логотип рабочего режима. imageDark— для темного или цветного заголовка, а imageLight— для светлого заголовка, например, серой темы. url— определяет, куда будет при нажатии на логотип; установите его в пустую строку или nullукажите, должен ли логотип быть кликабельным. visible— определяет, отображается ли логотип.

Шаг 4: проверьте логотип как при свете, так и в темноте.

Откройте реальный документ, интегрированный с вашей системой, и проверьте заголовок при обычном масштабировании в браузере. Успешный результат — это не просто «файл загружен». Логотип должен быть четким, расположенным по центру по вертикали, читаемым при компактной высоте заголовка и без неожиданных фоновых блоков. Также убедитесь, что щелчок по нему работает должным образом.

Затем переключитесь на темный интерфейс и повторите проверку. Если логотип станет низкоконтрастным, используйте специальный imageDarkграфический элемент, а не пытайтесь заставить один и тот же графический элемент работать везде.

Шаг 5: создайте JSON-файл пользовательской цветовой темы.

Для цветов интерфейса создайте файл темы, idначинающийся с theme-. ONLYOFFICE documents lightи darkсодержащий допустимые типы тем, а также поддерживающий цвета в шестнадцатеричной или RGBA-нотации. Не путайте это с цветовой схемой документа: этот JSON изменяет сам интерфейс редактора, а не цвета темы, хранящиеся в файле DOCX, XLSX или 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"
  }
}

Приведенные выше значения представляют собой пример палитры, а не предписанную тему ONLYOFFICE. Названия параметров являются документированными переменными темы. В рабочей среде начните с небольшого набора значений, оказывающих сильное влияние, просмотрите результат, а затем расширяйте их только по мере необходимости. Это упростит выявление низкого контраста или несогласованных состояний.

Шаг 6: поместите файл темы в каталог тем на сервере документов.

В документации ONLYOFFICE указаны следующие места расположения файлов пользовательских тем:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Окна: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: скопируйте JSON-файл в тот же путь внутри контейнера Docs.

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

Замените onlyofficeна фактическое имя или идентификатор вашего контейнера. Если ваша система развертывания часто перестраивается, не полагайтесь на одноразовую копию как на единственный источник достоверной информации. Внедрите тему в процесс развертывания, настройку образа или другой механизм постоянного хранения, подходящий для вашей среды, чтобы обновления и замена контейнеров не удаляли ее автоматически.

Шаг 7: обновите страницу, дождитесь загрузки кеша и выберите пользовательскую тему.

В официальном руководстве отмечается, что время жизни кэша сервера для запроса темы составляет пять минут. После размещения файла подождите эту задержку и обновите редактор. В некоторых случаях ONLYOFFICE также рекомендует перезапустить службы и очистить кэш, если тема не отображается.

После загрузки тема должна появиться в списке тем интерфейса в расширенных настройках. Выберите её и изучите не только заголовок. Проверьте меню, диалоги, выбранные вкладки, состояния при наведении курсора, отключенные элементы управления, значки, значки уведомлений и контрастность текста.

Шаг 8: проверьте готовый бренд как систему, а не просто скриншот.

Хороший фирменный стиль должен сохраняться при обычном использовании редактора. Откройте документ, электронную таблицу, презентацию и PDF-файл, если эти редакторы входят в область действия. Попробуйте стандартные диалоговые окна и элементы управления для совместной работы. Проверьте работу в светлом и темном режимах, если вы предлагаете оба варианта. Проверьте фокус клавиатуры, состояния отключения, контрастность при наведении курсора и длинные имена файлов. Цвет, который выглядит привлекательно в заголовке, может все еще затруднять чтение выделенной вкладки или дополнительного текста.

Как понять, что настройка работает?

Успешную реализацию можно считать завершенной, если настроенный логотип отображается стабильно, правильный вариант логотипа остается читаемым в активном заголовке, пользовательская тема отображается в палитре тем, фирменные цвета отображаются без нарушения контраста текста или значков, а пользовательский интерфейс остается удобным для всех типов редакторов, которые фактически открывают ваши пользователи.

Если логотип не меняется, несмотря на корректную передачу объекта конфигурации, сначала подтвердите версию и лицензию, поскольку в справочнике API параметр логотипа помечен как предназначенный только для разработчиков. Если цветовая тема никогда не отображается, проверьте идентификатор и синтаксис JSON, расположение файла, сохранение данных в контейнере, время кэширования и состояние службы. Если тема загружается, но выглядит неправильно, сократите настройку до меньшего набора документированных переменных и добавляйте цвета постепенно.

Распространенные границы и ошибки

Брендирование редактора — это не то же самое, что брендирование DocSpace или Workspace.

В ONLYOFFICE есть отдельные элементы настройки. Это руководство посвящено именно брендингу редактора документов ONLYOFFICE. Элементы управления брендингом портала, названия арендаторов, значки портала и окружающая навигация относятся к настройкам DocSpace или Workspace, а не к объекту логотипа заголовка Docs API.

Цветовая схема документа — это не тема интерфейса.

Цветовые схемы документа влияют на содержимое, такое как текст, таблицы, диаграммы и фигуры. Пользовательская тема интерфейса управляет элементами пользовательского интерфейса редактора, такими как панели инструментов, панели, кнопки, значки, границы и подписи. Выберите механизм, соответствующий типу поверхности, которую вы хотите изменить.

Не следует предполагать, что все элементы управления, доступные под чужим брендом, входят в стандартную комплектацию.

ONLYOFFICE разделяет стандартный брендинг и расширенные параметры брендирования. Если вам необходим более широкий контроль над такими элементами, как шрифты интерфейса, видимость макета или элементы, связанные с разделом «О программе», перед планированием внедрения ознакомьтесь с текущими требованиями к лицензированию в официальном справочнике по брендированию .

Практический контрольный список развертывания

• Если вам необходима настройка логотипа в заголовке, описанная здесь, обратитесь к разработчику ONLYOFFICE Docs.
• Создавайте логотипы размером 300×20 пикселей, включая светлые и темные варианты там, где это необходимо из-за контраста.
• Настройте editorConfig.customization.logoна уровне интеграции.
• Создайте действительный JSON-файл пользовательской темы с идентификатором, начинающимся с theme-.
• Поместите файл темы в каталог тем Document Server, указанный в документации.
• Для развертывания в Docker или неизменяемых средах сделайте установку темы повторяемой и постоянной.
• Дождитесь указанной в документации задержки кэширования, затем обновите страницу и выберите тему оформления.
• Перед широким внедрением протестируйте контрастность, состояния, типы редактора, а также условия освещения (свет и темнота).

Если концептуально разделить фирменную символику, оформление интерфейса и расширенные элементы управления, ONLYOFFICE Docs становится гораздо проще и предсказуемее настраивать. Начните с самых незначительных изменений, обеспечивающих желаемое соответствие фирменному стилю, проверьте их в реальных условиях редактирования, и только потом расширяйте тему оформления.

Официальные ссылки

• API для работы с документами OnlyOffice: Настройка – Стандартный брендинг
• Центр поддержки ONLYOFFICE: Изменение тем оформления интерфейса в документах ONLYOFFICE
• API для работы с документами OnlyOffice: Настройка – брендирование