Koha System

What Changed in Recent Koha OPAC Customization Options (24.11 / 25.05 / 25.11)

A version-by-version guide to what's changed in Koha OPAC customization from 23.11 through 25.11 — including per-branch CSS/JS, Bootstrap 5 migration risks, and what to check before upgrading.

April 14, 2026 7 min read

Koha’s OPAC customization options have evolved significantly over the last five releases. The most significant additions are per-branch UserCSS and UserJS (introduced in 23.11), incremental improvements to the HTML customization tools, and the ongoing Bootstrap 5 migration — which carries real upgrade risk for any library with heavy CSS customization. This guide summarises the changes that matter most across 23.11 through 25.11.

For a full overview of Koha’s customization system, see the Koha Customization Guide.

How Koha Releases Work

Koha follows a six-month release cycle: major versions ship in May and November each year. The version numbers reflect this — 23.11 shipped November 2023, 24.05 shipped May 2024, and so on. Security and bug-fix point releases (e.g. 24.11.01) land between majors.

This cadence matters for planning: each major release can introduce new preference names, change template structure, or reclassify Bootstrap classes — any of which can silently break existing OPACUserCSS customizations.

Official release notes: koha-community.org/category/releases/
Koha manual: koha-community.org/manual/

What Changed by Version

Version	Release	Key Customization Changes
23.11	Nov 2023	Per-branch `UserCSS` and `UserJS` system preferences; HTML customization region refinements
24.05	May 2024	HTML customizations tool improvements; additional content region granularity
24.11	Nov 2024	Continued Bootstrap 5 migration; accessibility improvements; preference reorganization
25.05	May 2025	Continued Bootstrap 5 migration; search UX improvements; OPAC UI polish
25.11	Nov 2025	Further Bootstrap 5 completion; OPAC template accessibility pass; preference interface improvements

23.11 — Per-Branch CSS and JS

The headline change for customizers in 23.11 was the introduction of UserCSS and UserJS system preferences scoped at the branch (library) level. Previously, OPACUserCSS and OPACUserJS were global — one set of rules applied to every patron regardless of which branch they logged in through.

From 23.11 onward, you can set distinct CSS and JS overrides per branch, layered on top of the global preferences. This is particularly useful for library systems with multiple branches that have different branding, colour schemes, or feature toggles.

What to check: If you manage a multi-branch Koha system, review your Koha administration panel under System Preferences → OPAC to find the new per-branch fields.

24.05 — HTML Customizations Tool Improvements

The 24.05 release brought incremental improvements to the HTML customizations tool — the interface that manages regions such as OpacNav, OpacNavBottom, OpacMainUserBlock, opacheader, and OPACResultsSidebar. These regions allow librarians to inject HTML content without writing full templates.

24.05 increased granularity in some content regions and improved the editing experience within the tool itself. If you previously worked around limitations in how content was inserted into OpacMainUserBlock or the navigation regions, the 24.05 behaviour may differ slightly — worth testing after upgrade.

24.11 — Bootstrap 5 Migration Progress and Accessibility

24.11 continued the multi-release effort to migrate Koha’s OPAC from Bootstrap 3/4 to Bootstrap 5. This is not a single-release change — it is an incremental migration that has been underway across several versions and continued into 25.05.

Alongside the Bootstrap work, 24.11 introduced accessibility improvements across the OPAC templates and some reorganisation of system preference categories, which may require updating any documentation your team has on where specific preferences live.

25.05 — What Changed

25.05 (May 2025) continued the Bootstrap 5 migration, with further improvements to search results UX and general OPAC modernization. As with any major release, test your CSS customizations in a staging environment before upgrading production.

25.11 — Further Bootstrap 5 Progress and Accessibility

25.11 (November 2025) continued the Bootstrap 5 migration and included a pass on OPAC template accessibility improvements. Libraries maintaining OPACUserCSS customizations that target Bootstrap 4 utility classes — especially directional utilities like .float-left, .ml-*, .mr-* — should retest after upgrading to 25.11, as the Bootstrap 5 class substitutions (.float-start, .ms-*, .me-*) are progressively landing across this release cycle.

The preference interface also saw minor reorganization in 25.11; verify that your key preferences (OPACUserCSS, OPACUserJS, OpacMainUserBlock, opacheader) are intact after any upgrade.

Official 25.11 release notes: koha-community.org/category/releases/

The Bootstrap 5 Migration — Upgrade Risk You Need to Know About

This is the single most important thing to understand if your library maintains any OPACUserCSS customization.

Koha’s OPAC templates have historically been built on Bootstrap 3, with some 4-era elements. Bootstrap 5 introduced breaking class-name changes:

.left / .right → .start / .end (directional utilities)
.float-left → .float-start
.ml-* / .mr-* → .ms-* / .me-*
.badge-* colour variants changed
Flexbox utility names reorganized

If your OPACUserCSS targets Bootstrap class names directly — for example, overriding .nav-item, .card, or .badge-primary — those rules may silently stop applying after an upgrade that advances the Bootstrap migration. The OPAC will still render, but your visual customizations may disappear or break.

Practical protection steps:

Keep a written record of every class you override in OPACUserCSS
Use a staging Koha instance to test upgrades before pushing to production
Prefer targeting your own custom classes added via opacheader or OpacMainUserBlock HTML, rather than Bootstrap utility classes
Use OPACXSLTResultsDisplay carefully — template changes in new versions can affect how XSLT output is structured

Why Staying Current Still Matters

Despite the upgrade overhead, running an outdated Koha version carries real risk:

Security patches are backported to supported versions, but older releases eventually fall out of support
Browser compatibility issues accumulate on older templates
Community support is harder to get for versions more than two releases behind

The Koha community’s recommended approach is to stay within one major version of the current release. Check koha-community.org/category/releases/ for the current supported versions.

How Theme Builder Manages Upgrade Risk

Libraries using Koha Theme Builder™ don’t write CSS against Bootstrap class names. Theme Builder’s approach uses semantic design tokens — CSS custom properties like --ks-primary and --ks-accent — so the theme layer is decoupled from Bootstrap’s utility class structure.

When Koha’s templates update Bootstrap classes underneath, the theme layer’s design tokens remain stable. This is a deliberate architectural choice: upgrade-safe theming that doesn’t require re-patching CSS after every Koha release.

Frequently Asked Questions

How often should I update Koha?
Aim to stay on a supported version — ideally within one major release of the latest. Koha releases every six months; a practical cadence for most libraries is to upgrade once per year, testing on a staging instance first.

How do I know if my CSS broke after a Koha upgrade?
Load your OPAC in a browser, open developer tools, and inspect the elements your customizations target. If expected styles are missing, check whether the class names on those elements have changed. Compare against the Koha manual for your new version.

What is the Bootstrap 5 migration?
Koha is gradually updating its frontend framework from Bootstrap 3/4 to Bootstrap 5. Bootstrap 5 changed many utility class names. If your OPACUserCSS targets those classes directly, upgrading Koha can silently break your customizations. The migration is happening across multiple Koha releases.

Where are the official Koha release notes?
At koha-community.org/category/releases/. Each release has a dedicated page listing new features, enhancements, and bugs fixed.

Do system preference names change between versions?
Occasionally. Koha has renamed or reorganized preferences across releases. After upgrading, verify that preferences like OPACUserCSS, OPACUserJS, OpacNav, and OpacMainUserBlock are still in their expected location and that their values are intact.

Upgrade-Safe OPAC Customization with KohaSupport

If managing Bootstrap class changes across Koha upgrades is becoming a maintenance burden, KohaSupport’s hosted Koha platform and Koha Theme Builder™ are built around upgrade safety from the ground up.

Explore Koha Theme Builder™ →

Not sure where to start? We’re happy to review your current OPAC setup and help you plan an upgrade-safe customization approach.

Book a consultation →