Koha System

How to Modernize the Koha OPAC Without Rebuilding the Whole Frontend

You can modernize the Koha OPAC through CSS and preference blocks — but deeper improvements require Template Toolkit work or a theme overlay. Here's what each level of effort actually achieves.

January 15, 2025 8 min read

You can meaningfully improve how Koha’s OPAC looks and feels using native preferences and CSS — but there’s a hard ceiling. Quick wins like brand colors and typography are achievable without touching core files. Beyond that, real modernization requires either editing Koha’s Template Toolkit templates (which is complex and maintenance-heavy) or using a theme overlay system like Theme Builder that handles the complexity for you.

This guide covers all three levels of modernization so you can make an informed decision about what your library actually needs.

For the full picture of Koha customization options, start with the Koha Customization Guide.

Why the Default Koha OPAC Looks Dated

Koha ships with a Bootstrap-based OPAC that is functional but generic. The default design hasn’t changed dramatically in years, and for good reason — Koha’s development priorities are cataloging, circulation, and ILS features, not visual polish.

The result is that most Koha OPACs end up looking similar to each other, with little visual differentiation or institutional branding. If you want a modern patron experience, you face a clear choice: invest in customization, or live with the default.

The problem is that the customization path in Koha is fragmented. There’s no single “theme” file or interface to update — changes are spread across dozens of system preferences, each controlling a small piece of the layout. Meaningful design changes require either significant coding skill or a structured approach.

The Three Levels of Koha OPAC Modernization

Level 1 — Quick Wins with OPACUserCSS

The fastest path to a more institutional-looking OPAC is OPACUserCSS. With a focused set of CSS rules, you can:

Override the default Bootstrap colors with your library’s brand palette
Swap in a custom font via a Google Fonts import
Restyle the header bar with a background color and logo
Increase font sizes for readability
Adjust spacing to reduce the crowded default layout

Example: setting a brand color on the header

#header {
  background-color: #1a4a7a;
  border-bottom: 3px solid #f4a020;
}
#header a {
  color: #ffffff;
}

This approach is quick — an experienced CSS user can make a Koha OPAC look substantially more modern in a few hours. But it has real limitations:

CSS changes are cosmetic only; they can’t restructure the page
Koha upgrades can change class names or HTML structure, breaking your CSS silently
There’s no preview environment — you’re editing live
Every workaround creates technical debt that compounds over time

The next level uses OpacMainUserBlock, opacheader, OpacNav, and OpacNavBottom to inject custom HTML into key positions on the page. This is more impactful than CSS alone because you’re adding content and structure — not just restyling.

Practical examples at this level:

A full-width hero section on the homepage built inside OpacMainUserBlock
A top navigation bar with links to databases, branches, and your main website via opacheader
A curated sidebar in OpacNavRight with featured collections or staff picks
Quick links panels that give first-time patrons a starting point

This is where many libraries stop — and it’s a reasonable outcome. Your OPAC — with a well-built opacheader, a styled OpacMainUserBlock homepage section, and clean navigation — can look genuinely polished.

The limitation: these blocks are disconnected from each other and from the rest of the OPAC. Search results, record detail pages, and the patron account look exactly as they did before. The OPAC still doesn’t have a coherent visual identity across all page types.

Level 3 — Real Redesign: Template Editing or Theme Builder

A fully modern OPAC — one where the search results page, catalog record page, and patron account page all reflect your brand — requires changes to Koha’s Template Toolkit templates. These are the .tt files that control the HTML structure of every OPAC page.

Template editing gives you complete control, but it comes at a cost:

You must maintain a copy of the modified templates separately from Koha core
Every Koha upgrade requires reviewing your changes against the new template files and merging differences manually
A mistake in a template can break OPAC functionality, not just appearance
It requires familiarity with Template Toolkit (TT2) syntax, Koha’s variable system, and OPAC page routing

This is developer work. Most libraries shouldn’t attempt it without in-house development capacity or a dedicated Koha consultant.

Theme Builder is the alternative path to Level 3 results without the maintenance burden. It provides a structured overlay system where your design is applied across all OPAC page types — homepage, search results, record detail, patron account — through a plugin rather than direct template edits. When Koha upgrades, Theme Builder handles the compatibility layer.

What a Modern Koha OPAC Actually Needs

Before deciding on approach, it helps to be clear about what “modern” actually means for a library catalog:

Clear visual hierarchy — patrons should know instantly where to search, where to log in, and where to find help
Institutional branding — colors, fonts, and logo that match your library or parent organization
Search-first layout — the search bar should be the most prominent element, not buried
Mobile-responsive design — most patrons use phones; the default Koha OPAC is responsive but the preference blocks can break this if not built carefully
Consistent typography — a professional OPAC uses 2 fonts maximum with a clear type scale
Readable result cards — the default search result display is dense; modernization often includes simplifying this

CSS changes alone address the visual branding items. Navigation blocks address discovery. Real layout changes — particularly to search results and record display — require Level 3 work.

The Hidden Cost of the CSS-Only Approach

Many libraries start with OPACUserCSS patches and accumulate changes over years. The result is often hundreds of lines of CSS with no documentation, conflicting rules, and changes that nobody remembers making.

When a Koha upgrade arrives, the CSS either works fine, partially breaks, or silently stops doing what it was supposed to — because a class name changed upstream. There’s often no way to tell without manually checking every page of the OPAC.

The CSS-only approach also creates a false confidence. It looks polished until you navigate off the homepage — then search results and record pages reveal that only the surface was touched.

The ongoing maintenance cost of accumulated CSS workarounds often exceeds the one-time cost of doing it properly — which is why the same conclusion comes up so often: a structured approach is worth it.

Frequently Asked Questions

How long does a Koha OPAC modernization project take? Level 1 CSS work can be done in a day by someone comfortable with CSS. Level 2 with full preference blocks takes a few days to a week for a thoughtful implementation. Level 3 — template editing or Theme Builder onboarding — is typically a multi-week project including design, implementation, and testing.

Can I do this myself without a developer? Level 1 and Level 2, yes — if you’re comfortable with CSS and basic HTML. Level 3 template editing requires developer skill. Theme Builder is designed to make Level 3 results achievable without custom development.

Will my customizations survive a Koha upgrade? OPACUserCSS and preference-based customizations generally survive upgrades, though CSS may break if Koha changes class names. Template edits require manual merging after every upgrade. Theme Builder is maintained to be upgrade-compatible by KohaSupport.

What does a Koha OPAC modernization project cost? It depends heavily on scope. CSS-only work is low cost if done in-house. A full Level 3 redesign with custom template development from a consultant can run into thousands of dollars. Theme Builder is a subscription product — contact us for current pricing.

Does a modern OPAC improve patron usage? Anecdotally, yes. Libraries that have modernized report that patrons find the catalog less confusing, self-service checkouts increase, and staff spend less time helping patrons navigate the search interface. There’s no universal data, but patron experience is a real factor in catalog adoption.

Ready to Modernize Your Koha OPAC?

This is one of the more consequential decisions you’ll make about your catalog. We’re happy to talk through what level of modernization makes sense for your library.

Book a Consultation → Talk to the KohaSupport team about your OPAC goals, your technical capacity, and the most practical path forward for your library.

Explore Theme Builder → See what Level 3 OPAC modernization looks like with Theme Builder — full-OPAC design coverage, upgrade-safe, no custom development required.

For implementation details, start with the Theme Builder Documentation Hub and then Getting Started with Theme Builder.