Koha Customization Guide

Koha customization: a complete guide to every native tool and when to use them

Koha gives your library more built-in customization options than you might expect. This guide documents every native method — from simple system preferences to XSLT overrides — and explains where native tools end and a proper theme begins.

Book a consultationExplore Theme Builder

Trusted by thousands of libraries worldwide

What Koha OPAC customization actually covers

Koha ships with a robust set of customization hooks that let you change the look, structure, and content of the public catalog without touching the underlying code. The challenge is not that the tools are lacking — they are scattered across five or six separate system preferences, each controlling a different slice of the OPAC, with no unified editing interface and no built-in preview. If your library has a developer on staff, you can assemble a polished OPAC from these primitives. Most libraries can't — and shouldn't have to.

This guide covers every native customization method Koha provides, what each one actually controls, its practical limitations, and the point at which a purpose-built theme system like Koha Theme Builder™ becomes the better path.

Why OPAC customization matters for libraries

First impression is the catalog

For most patrons, the OPAC is the library's digital presence. A generic Koha installation with default Bootstrap styling signals nothing about the institution behind it. A well-customized OPAC communicates brand, tone, and confidence before the first search.

Patron experience drives engagement

Clear navigation, a usable homepage, and readable search results directly affect whether patrons find what they are looking for — and whether they return. This is not cosmetic; it is functional.

Koha already supports it — if you know where to look

You might hire an external developer for work Koha can already handle natively — and this guide aims to prevent that. Understanding the built-in toolkit prevents unnecessary cost and avoids customizations that break on upgrade.

Every native Koha customization method explained

These tools are available in every standard Koha installation via Administration → System Preferences. No server access or developer skill is required to use most of them.

HTML customization preferences

Koha provides several system preferences that accept raw HTML and inject it into specific regions of the OPAC. These are the most commonly used customization entry points:

Preference Where it appears Typical use
OpacNav Left sidebar column on the OPAC homepage Navigation links, quick links to subject lists, branch hours
OpacNavBottom Below OpacNav in the left sidebar Secondary links, social media, footer nav overflow
opacheader At the very top of every OPAC page, above the search bar Institution logo, banner message, site-wide alert
OpacMainUserBlock Main content area of the OPAC homepage Welcome message, featured collections, news, event listings
OPACResultsSidebar Sidebar on the search results page Search tips, subject guides, database links
OpacMoreSearches Below the main search bar Links to external databases, federated search, ILL request

Practical example: If you want a welcome panel on the homepage that introduces your library and links to new arrivals, put that HTML in OpacMainUserBlock. If you want branch hours in the sidebar, add them to OpacNav. In a multi-branch setup, each of these preferences can be scoped per library — a branch can show different content than the system default.

Pages tool (custom OPAC pages)

Introduced in Koha 22.11 and improved in subsequent releases, the Pages tool (Tools → OPAC → Pages) lets staff create full custom pages that are served directly through the OPAC at a configurable URL. Key capabilities:

  • Per-library scoping — pages can be restricted to a specific library branch or made global across all branches
  • Multilingual support — separate content blocks per language for multilingual installations
  • No server access required — pages are created and edited entirely within the Koha staff interface
  • Published/draft states — pages can be drafted and reviewed before going live

The Pages tool replaces the older workaround of embedding everything in OpacMainUserBlock and using hash-link navigation. If your Koha is on 22.11 or later, use Pages for any content that deserves its own URL: an about page, collection policy, event calendar, or digital resource guide.

OPACUserCSS and OPACUserJS

OPACUserCSS injects CSS into the <head> of every OPAC page. OPACUserJS injects JavaScript at the bottom of the OPAC body. Both are site-wide by default, with per-library overrides available through the library-level settings.

These are the most powerful native customization levers. With OPACUserCSS alone, you can:

  • Override colors, fonts, and spacing throughout the OPAC
  • Hide elements you do not want patrons to see (specific facets, tag clouds, breadcrumbs)
  • Restyle the header, footer, search bar, and navigation bar
  • Change hover states, button styles, and link colors
  • Add custom layout rules to the homepage or results page

OPACUserJS unlocks behavioral changes: rearranging DOM elements, adding interactive components, integrating third-party widgets (chat, accessibility tools, federated search), or modifying how search results render before Koha's own scripts run.

The limitation: Both preferences are plain text fields in the staff interface — no syntax highlighting, no linting, no version control, no preview. A CSS typo that breaks the stylesheet breaks the OPAC for every patron immediately. Your library may accumulate years of CSS in these fields with no record of what each rule does or why it was added.

Library-level UserCSS and UserJS

Each library branch in Koha can have its own CSS and JS overrides (set in Administration → Libraries → edit the library → OPAC settings), applied on top of the global OPACUserCSS/OPACUserJS when a patron session is associated with that branch. This allows multi-branch systems to give each branch a distinct visual identity while sharing a common base. The editing interface is the same plain text field — with the same limitations.

XSLT customization

Koha uses XSLT stylesheets to transform MARC records into the HTML displayed on search results and bibliographic detail pages. Two system preferences control which stylesheets are used:

  • OPACXSLTResultsDisplay — controls the XSLT applied to each search result row. Set to default to use Koha's built-in stylesheet, or point to a file path on the server to use a custom one.
  • OPACXSLTDetailsDisplay — controls the XSLT applied to the full bibliographic detail page. Same default/custom logic applies.

Custom XSLT lets you change exactly which MARC fields are displayed, how they are labeled, the order they appear, and how linked fields (series, subjects, authors) render — without modifying Perl templates or Ruby code.

Who needs this: Libraries with unusual MARC practices, institutions displaying fields Koha does not show by default (583 action notes, local 9XX fields, custom indicators), or any site that needs fundamentally different search result structure. XSLT requires XML/XSLT knowledge and server file access to deploy the custom stylesheet.

The limitations of the native approach

Each native tool works as documented. The overall system has structural weaknesses that compound over time, especially without a dedicated developer.

Fragmented editing model

Your library's visual identity ends up split across six or more separate fields in system preferences. Changing the primary color means hunting through OPACUserCSS. Changing homepage content means editing OpacMainUserBlock. There is no single file or view that represents "the theme."

No version control or rollback

Koha logs system preference changes, but there is no built-in way to preview a change before it goes live, or roll back to a known-good state without manually restoring old text. CSS mistakes are immediately visible to every patron.

Developer skill required for real results

Getting a polished OPAC from OPACUserCSS requires understanding CSS specificity, Bootstrap's grid system, and Koha's template structure. The tools are available but the knowledge barrier is high for non-technical staff.

Upgrade fragility

When Koha changes its Bootstrap version or restructures templates, custom CSS targeting specific class names or DOM structures can silently break. Testing CSS after every Koha upgrade is essential but time-consuming and easy to skip.

No design coherence guarantee

Nothing in the native system enforces visual consistency. It is easy to end up with a homepage that looks one way, search results that look another, and the patron account page that looks like a third thing — because each was edited at a different time by a different person.

Multi-branch complexity grows fast

In a system with 5, 10, or 20 branches, managing per-library CSS overrides that inherit from a global base becomes difficult to reason about. What a patron sees depends on which library they are associated with and which overrides are active at each level.

When Koha Theme Builder™ makes sense

Theme Builder is not a replacement for every native customization — it solves a specific problem: libraries that want a professional, coherent OPAC appearance without building one from scratch in CSS text fields.

Consider Theme Builder when:

  • Your current OPAC looks like a default Koha install and you want something that reflects your library's brand without a multi-month design project.
  • You have accumulated years of CSS in OPACUserCSS with no documentation, and you are not sure what half of it does. A clean theme gives you a known baseline to work from.
  • You are migrating to Koha from another ILS and want the public catalog to feel polished from day one rather than launching with the default Bootstrap look.
  • You run a multi-branch consortium and want each branch to have its own visual identity within a consistent structural framework — without maintaining independent CSS blobs per branch.
  • You need accessibility compliance and want a theme built with WCAG 2.1 AA in mind from the start, not retrofitted via CSS overrides.
  • You do not have a developer and cannot reliably maintain bespoke CSS across Koha upgrades without introducing regressions.

Theme Builder packages CSS, JavaScript, template overrides, and content blocks into a versioned, installable Koha plugin. Theme compatibility is validated against the Koha version on your hosted instance before any upgrade reaches you. Your customization does not silently break on the next community release.

Frequently asked questions

Can I customize the Koha OPAC without coding?

To a limited extent. System preferences like OpacMainUserBlock and OpacNav accept HTML, which requires at least basic markup knowledge. True styling changes — colors, fonts, layout — require CSS in OPACUserCSS. There is no point-and-click design tool built into Koha itself. Koha Theme Builder™ provides structured themes that non-developers can deploy and configure without writing CSS from scratch.

What is the difference between OPACUserCSS and a Koha theme?

OPACUserCSS is a system preference field where you paste CSS that gets injected into every OPAC page. A theme (in the Theme Builder sense) is a complete, versioned package — CSS, JavaScript, template overrides, and content structure — installed as a Koha plugin. The difference is coherence, maintainability, and upgrade safety. OPACUserCSS is a single text field with no tooling; a theme is a software artifact with a release cycle and tested compatibility.

Will Koha OPAC customizations survive an upgrade?

HTML in system preferences (OpacNav, OpacMainUserBlock, opacheader, etc.) generally survives upgrades intact — Koha carries these values forward. CSS in OPACUserCSS survives as text but may stop working correctly if Koha changes its template structure or upgrades Bootstrap. XSLT overrides require explicit testing against every Koha release. Theme Builder themes are versioned and tested against supported Koha versions before release to customers.

Can different branches have different OPAC appearances?

Yes. Koha supports per-library values for OpacNav, OpacNavBottom, OpacMainUserBlock, and the library-level UserCSS/UserJS fields. Each branch can show different content and styling when patrons are logged in under that branch. Theme Builder supports per-branch presets within a shared theme family, which is easier to manage than maintaining independent CSS blobs per branch.

What is the Pages tool and when should I use it?

The Pages tool (available since Koha 22.11) lets you create custom OPAC pages — with their own URLs — directly from the Koha staff interface. Use it for content that deserves a permanent, linkable page: an about page, branch hours and directions, collection guides, digital resource listings, or event archives. It replaces the older workaround of embedding all content in OpacMainUserBlock and navigating with hash links.

Do I need server access to customize the Koha OPAC?

For most customizations — all the HTML preference fields, OPACUserCSS, OPACUserJS, the Pages tool — no server access is required. Everything is done through the staff interface. Server access is only needed for XSLT overrides (placing a custom XSLT file on the server) and for installing Koha plugins. KohaSupport customers have XSLT customization and plugin installation handled as part of the managed hosting relationship.

Related guides in this series

Each guide below covers one aspect of Koha OPAC customization in depth, with step-by-step instructions and practical examples.

Not sure which customization approach fits your library?

We have helped libraries across every size and type find the right path — from simple system preference fixes to full Theme Builder deployments. A short consultation costs nothing.

Explore Theme Builder Book a consultation