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

Pregătiți un logo lat și simplu, care să rămână lizibil la o înălțime a antetului de 20 de pixeli. Documentația API specifică o dimensiune a imaginii de 300×20 pentru variantele standard de imagine a antetului. Folosiți grafică separată pentru fundaluri întunecate și deschise atunci când marca dvs. ar pierde contrast. De exemplu, un logotip bleumarin închis poate funcționa pe un antet palid, dar poate dispărea pe o temă întunecată; o variantă albă sau deschisă rezolvă acest lucru.

Găzduiți imaginile la adrese URL HTTPS stabile pe care editorul le poate încărca. Evitați adresele URL semnate de scurtă durată dacă sigla trebuie să fie disponibilă în mod constant. De asemenea, testați resursele prin aceeași cale de rețea și politică de securitate a browserului utilizate de utilizatorii reali.

Pasul 3: adăugați sigla la configurația API-ului 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);

imageeste sigla obișnuită pentru modul de lucru. imageDarkeste pentru un antet închis sau colorat și imageLighteste pentru un antet deschis la culoare, cum ar fi tema Gri. urlcontrolează unde merge un clic pe siglă; setează-l la un șir gol sau nulldacă sigla nu ar trebui să fie accesibilă cu clic. visiblecontrolează dacă sigla este afișată.

Pasul 4: verificați sigla atât în ​​condiții de lumină, cât și în întuneric

Deschideți un document real prin integrarea dvs. și verificați antetul la zoom normal al browserului. Un rezultat reușit nu este doar „fișierul încărcat”. Logo-ul trebuie să fie clar, centrat vertical, lizibil la înălțimea compactă a antetului și fără casete de fundal neașteptate. De asemenea, verificați dacă un clic se comportă conform așteptărilor.

Apoi, comutați la o condiție de interfață întunecată și repetați verificarea. Dacă logo-ul devine cu contrast scăzut, utilizați o imageDarkresursă dedicată, în loc să încercați să forțați o grafică să funcționeze peste tot.

Pasul 5: creați o temă de culori personalizată JSON

Pentru culorile interfeței, creați un fișier temă care idîncepe cu theme-.onlyoffice documente lightși darkca tipuri de teme valide și acceptă culori în notație hexazecimală sau RGBA. Nu confundați acest lucru cu o schemă de culori a documentului: acest JSON modifică editorul Chrome în sine, nu culorile temei stocate într-un fișier DOCX, XLSX sau 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"
  }
}

Valorile de mai sus reprezintă o paletă de exemple, nu o temă ONLYOFFICE prescrisă. Numele parametrilor sunt variabile de temă documentate. În producție, începeți cu un set mic de valori cu impact ridicat, previzualizați rezultatul, apoi extindeți doar după cum este necesar. Acest lucru facilitează detectarea contrastului slab sau a stărilor inconsistente.

Pasul 6: plasați fișierul temei în directorul temei Document Server

ONLYOFFICE documentează aceste locații pentru fișierele temelor personalizate:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Ferestre: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: copiază JSON-ul în aceeași cale din interiorul containerului Docs.

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

Înlocuiți onlyofficecu numele sau ID-ul real al containerului. Dacă implementarea este reconstruită frecvent, nu vă bazați pe o copie unică ca singura sursă de încredere. Includeți tema în procesul de implementare, în personalizarea imaginilor sau în alt mecanism persistent adecvat mediului dvs., astfel încât actualizările și înlocuirea containerelor să nu o elimine în mod silențios.

Pasul 7: actualizați pagina, așteptați memoria cache și selectați tema personalizată

Ghidul oficial menționează că memoria cache a serverului pentru solicitarea temei are o durată de viață de cinci minute. După plasarea fișierului, așteptați această întârziere și reîmprospătați editorul. În unele cazuri, ONLYOFFICE recomandă, de asemenea, repornirea serviciilor și golirea memoriei cache dacă tema nu apare.

După încărcare, tema ar trebui să apară în lista de teme Interfață din Setări avansate. Selectați-o și inspectați mai mult decât antetul. Verificați meniurile, casetele de dialog, filele selectate, stările de trecere a cursorului, controalele dezactivate, pictogramele, insignele de notificare și contrastul textului.

Pasul 8: validați brandul final ca sistem, nu doar ca o captură de ecran

Un brand personalizat bun ar trebui să supraviețuiască utilizării normale a unui editor. Deschideți un document, o foaie de calcul, o prezentare și un PDF dacă aceste editori sunt incluse în domeniu. Încercați dialoguri comune și controale de colaborare. Verificați atât condițiile de lumină, cât și cele de întuneric dacă le oferiți pe ambele. Verificați focalizarea tastaturii, stările dezactivate, contrastul la trecerea cursorului și numele lungi de fișiere. O culoare care arată atractiv în antet poate face totuși dificilă citirea unei file selectate sau a unui text secundar.

Cum să știi că personalizarea funcționează

Puteți considera implementarea reușită atunci când sigla configurată apare în mod constant, varianta corectă a siglei rămâne lizibilă în antetul activ, tema personalizată apare în selectorul de teme, culorile mărcii sunt redate fără întreruperea contrastului textului sau al pictogramelor, iar experiența rămâne utilizabilă în toate tipurile de editor pe care utilizatorii le deschid efectiv.

Dacă sigla nu se modifică niciodată, chiar dacă obiectul de configurare este transmis corect, confirmați mai întâi ediția și licența, deoarece referința API marchează parametrul siglei ca fiind doar pentru dezvoltatori Docs. Dacă tema de culoare nu apare niciodată, verificați ID-ul și sintaxa JSON, locația fișierului, persistența containerului, temporizarea memoriei cache și starea serviciului. Dacă o temă se încarcă, dar arată greșit, reduceți personalizarea la un set mai mic de variabile documentate și adăugați culori incremental.

Limite și greșeli comune

Brandingul editorului nu este același lucru cu brandingul DocSpace sau Workspace.

ONLYOFFICE are suprafețe de personalizare separate. Acest ghid se referă în mod specific la branding-ul editorului ONLYOFFICE Docs. Controalele de branding ale portalului, numele chiriașilor, favicon-urile portalului și navigarea din jur aparțin setărilor DocSpace sau Workspace, nu obiectului logo-ului antetului Docs API.

O schemă de culori a documentului nu este o temă de interfață

Schemele de culori ale documentelor afectează conținut precum text, tabele, diagrame și forme. O temă de interfață personalizată controlează elementele interfeței utilizator a editorului, cum ar fi barele de instrumente, panourile, butoanele, pictogramele, chenarele și etichetele. Alegeți mecanismul care se potrivește cu suprafața pe care doriți să o modificați.

Nu presupuneți că fiecare control white-label este inclus în brandingul standard

ONLYOFFICE separă brandingul standard de parametrii white-label extinși. Dacă aveți nevoie de un control mai amplu asupra unor elemente precum fonturile interfeței, vizibilitatea aspectului sau elementele legate de secțiunea „Despre”, verificați cerințele actuale ale licenței în referința oficială white-label înainte de a planifica implementarea.

Listă de verificare practică pentru implementare

• Confirmați colaborarea cu ONLYOFFICE Docs Developer dacă aveți nevoie de personalizarea logo-ului antetului descrisă aici.
• Creați elemente pentru logo de 300×20, inclusiv variante luminoase și întunecate acolo unde este necesar contrastul.
• Configurați editorConfig.customization.logoîn stratul de integrare.
• Creați o temă personalizată JSON validă cu un ID care începe cu theme-.
• Plasați fișierul temei în directorul de teme documentate al serverului de documente.
• Pentru implementări Docker sau imuabile, instalarea temei trebuie făcută repetabilă și persistentă.
• Permiteți întârzierea documentată a memoriei cache, apoi actualizați pagina și selectați tema.
• Testați contrastul, stările, tipurile de editori și condițiile de lumină și întuneric înainte de implementarea pe scară largă.

Când păstrezi separate conceptual brandingul logo-ului, tematizarea interfeței și controalele extinse white-label, ONLYOFFICE Docs devine mult mai ușor de personalizat în mod previzibil. Începe cu cea mai mică modificare care realizează potrivirea dorită cu brandul, verific-o în condiții reale de editor și abia apoi extinde tema.

Referințe oficiale

• API-ul ONLYOFFICE Docs: Personalizare – Branding standard
• Centrul de ajutor ONLYOFFICE: Schimbarea temelor de interfață în ONLYOFFICE Docs
• API-ul ONLYOFFICE Docs: Personalizare – White label