Koha System

Koha OPAC Themes vs OPACUserCSS Hacks: What's the Difference?

Most 'Koha themes' are OPACUserCSS customizations, not real theme systems. Learn the difference, why it matters, and what a proper Koha theme system actually delivers.

January 15, 2025 8 min read

Koha does not ship with selectable OPAC themes in the way WordPress or Drupal do. There is no theme chooser, no theme marketplace built into Koha, and no structured theme framework in the core codebase. What most vendors and documentation describe as a “Koha theme” is an OPACUserCSS customization — a collection of CSS rules pasted into a system preference. That is a meaningful distinction, and understanding it helps you make a better decision about how to brand your library’s catalog.

This article explains what OPACUserCSS customizations actually are, why they work but have structural limits, and what a proper theme system provides that CSS overrides cannot. For full context on all Koha OPAC customization tools, see the Koha Customization Guide.

What “Koha Theming” Actually Means in Practice

Koha’s OPAC is built on Bootstrap. The default visual style — blue nav bar, white background, standard Bootstrap form elements — comes from Bootstrap’s base CSS, layered with Koha-specific styles. When a library or vendor “themes” Koha, they write CSS rules that override Bootstrap’s defaults: different colors, different fonts, different header layout.

These overrides are delivered via the OPACUserCSS system preference (Administration → System Preferences → OPAC → Appearance). Koha outputs that CSS verbatim into a <style> tag on every OPAC page. The result can look genuinely good — a competent CSS developer can produce a polished, on-brand OPAC using this method.

Most “Koha themes” sold or shared online are exactly this: a text file of CSS rules, sometimes accompanied by a few lines of JavaScript in OPACUserJS, ready to paste into your system preference fields. That is the full extent of it.

This is not a criticism — OPACUserCSS is a legitimate tool and the right choice for smaller customizations. The problem is when it is packaged and sold as a “theme system” with implications of ongoing support, upgrade safety, and maintainability that a CSS file cannot structurally provide.

Why OPACUserCSS Customizations Are Fragile

CSS overrides work by targeting specific HTML elements using class names, IDs, and selectors. The entire approach depends on Koha’s HTML output remaining stable.

It does not. Koha releases happen frequently, and the HTML structure of the OPAC changes between versions: class names are renamed, elements are reorganized, Bootstrap is upgraded, new markup is added. When that happens:

.opac-main-search becomes a different element, and your brand color disappears from the search bar
.navbar-fixed-top is replaced with a different nav structure, and your header layout breaks
A Bootstrap upgrade changes how .btn classes render, and your button styles stop applying

The CSS file does not know Koha upgraded. Your “theme” silently degrades. The library notices when a patron calls to say the website looks broken, not when the admin saves the preference.

Additional fragility points:

No version control. Koha does not track changes to system preferences. An accidental overwrite loses your work.
No preview. Every save is immediately live to patrons.
Specificity conflicts. Bootstrap’s specificity can be hard to override cleanly, leading to !important proliferation that makes future changes harder.
No rollback. If a change breaks the layout, recovering the previous state requires you to have kept a separate backup.

What a Proper Theme System Provides

A proper theme system — as opposed to a CSS override file — is architecturally different in several ways:

Design tokens, not selector hunting. Instead of finding the right Bootstrap class to override, a theme system defines variables (colors, fonts, spacing) that propagate throughout the entire design. Change one token, and it updates everywhere correctly.

Layout components, not rules stacked on a default. A real theme can define its own navigation structure, footer layout, and homepage zones — not just restyle Koha’s defaults but provide new components that replace them.

Upgrade-aware design. A theme system maintains compatibility with the current Koha release shipped on your hosted instance. When Koha’s HTML changes, the theme is updated centrally and you get the fix without needing to audit your own selectors.

Preview before live. A theme system allows you to see the result before patrons do.

Structured delivery. Files, versions, a changelog — not a block of CSS in a text field.

Koha does not ship any of this natively. If you want it, it has to be built externally and delivered as a plugin or integration layer.

Comparison: OPACUserCSS Customization vs Proper Theme System

Capability	OPACUserCSS	Proper theme system
Applies custom colors and fonts	Yes	Yes
Custom layout zones (hero, content blocks)	Limited	Yes
Survives Koha version upgrades reliably	No — requires manual review	Yes — validated against your hosted Koha version
Visual preview before publishing	No	Yes
Version control / rollback	No	Yes
Design tokens (change one variable, update everywhere)	No	Yes
Delivered as maintainable, versioned files	No	Yes
Requires CSS/JS expertise to maintain	Yes	No
Multi-branch variant support	Manual, per-branch CSS	Structured

Koha Theme Builder™: A Real Theme Path for Koha

KohaSupport Theme Builder is a Koha plugin product that delivers a structured theme system on top of Koha’s OPAC for KohaSupport Standard and Enterprise deployments (self-service AWS launch or guided implementation). It provides:

Theme families — complete, cohesive designs (not just color swaps) with distinct layout systems for different library types
Design token architecture — colors, typography, and spacing defined as CSS custom properties that flow through the entire design
Upgrade-safe delivery — themes are maintained against current Koha releases; when Koha’s HTML changes, the plugin is updated
Homepage content blocks — structured zones for announcements, shelf highlights, events, and more, managed without editing template files
Plugin-based delivery — built as a Koha plugin and deployed/maintained by KohaSupport on supported Standard/Enterprise deployments

This is the structural difference: Theme Builder does not override Koha’s default OPAC at the selector level. It provides its own component layer delivered through supported Koha plugin hooks.

For a closer look at what the plugin delivers, see Koha Theme Builder™: Premium OPAC.

Frequently Asked Questions

Can I use a free Koha theme from GitHub? Yes. Most free Koha themes on GitHub are OPACUserCSS files — paste the contents into your system preference and it applies. Be aware these are typically maintained by the author who built them for a specific Koha version. If the Koha version changes or the author stops maintaining it, the theme may degrade without notice. It is a valid starting point but requires ongoing attention.

Are paid Koha themes just CSS files? Often, yes. Many vendors who sell “Koha themes” are delivering a CSS file and instructions to paste it into OPACUserCSS. That is not inherently bad — a well-written CSS customization can look professional — but it is architecturally the same as the free GitHub options, with the same upgrade risk. Ask vendors explicitly: what happens to my theme when Koha upgrades?

Does a Koha OPACUserCSS theme survive upgrades? Not automatically. After any Koha upgrade you should test your OPAC visually and check the key styled areas. If Koha’s HTML changed in a way that breaks your selectors, you will need to update the CSS manually. How much work this is depends on how structurally invasive the CSS customization is.

My library is on a hosted Koha service. Can I still use OPACUserCSS? Yes — OPACUserCSS and OPACUserJS are standard system preferences available on any Koha installation, including hosted services. You do not need server access to use them.

Does Theme Builder work with hosted Koha? Yes, on KohaSupport Standard and Enterprise deployments. It is not currently available as a standalone install for other hosting providers or self-managed Koha installations. If you’re on another provider and want to use Theme Builder, talk to us about a migration to KohaSupport.