OPAC & customization

OPACUserCSS and OPACUserJS: what belongs in each

Two system preferences hold your OPAC’s custom CSS and JavaScript. Here is what goes in each, what does not belong in either, and how to keep it upgrade-proof.

Updated 2026-08-09 · Tested against Koha 26.05

Custom CSS goes in the OPACUserCSS system preference and custom JavaScript in OPACUserJS — both under Administration → System preferences → OPAC. Koha injects them into every OPAC page, so they survive upgrades. IntranetUserCSS does the same for the staff interface. Editing theme files on disk does the same job today and is silently reverted by the next package upgrade.

Do not paste the tags

Koha wraps the contents of these preferences in <style> and <script> for you. Pasting the tags in as well produces a literal, broken block in the page — the single most common reason "my CSS does nothing".

OPACUserCSS — anything that is appearance

Colours, spacing, fonts, hiding an element, adjusting the layout at a breakpoint. Write plain CSS, no tags:

OPACUserCSS

/* Library brand colour on the masthead */#opac-main-search {    background-color: #1d3557;} /* Hide the "Most popular" tab we do not use */#news-container .tab-popular {    display: none;}

Find selectors with the browser, not by guessing

Right-click the element in your OPAC → Inspect. Koha gives most regions a stable id, and an id-based rule survives a theme update far better than one built from nested class names.

OPACUserJS — behaviour, and only when CSS cannot do it

jQuery is already loaded on OPAC pages, so this works without adding a library:

OPACUserJS

$ (document).ready(function () {    // Open every link to a PDF in a new tab    $('a[href$=".pdf"]').attr("target", "_blank");});

JavaScript here runs on every OPAC page, for every visitor

An error in this box breaks page behaviour catalogue-wide, and it is not obvious where it came from three months later.

Wrap work in $(document).ready() so it does not run before the element exists.
Guard anything page-specific with a check for the element rather than assuming it is there.
Test in a browser console first, then paste. Save with the console open and watch for errors.

A rule that can be written in CSS should be written in CSS. It is faster, it cannot throw, and it does not run again on every page load.

What does not belong in either

This is where older guides go wrong. Header text, footer credits, the navigation panel and the home-page blocks are content, and they moved out of system preferences into Tools → HTML customizations, backed by the additional_contents table. Building them out of injected JavaScript instead works until it does not, and cannot be edited by a librarian.

What you want to change	Where it actually lives
Colours, fonts, spacing, hiding things	`OPACUserCSS`
Behaviour that CSS cannot express	`OPACUserJS`
Text or links above the search bar	Tools → HTML customizations → `opacheader`
Footer credits	Tools → HTML customizations → `opaccredits`
Left-hand navigation links	Tools → HTML customizations → `OpacNav`
Home page content blocks	Tools → HTML customizations → `OpacMainUserBlock`
The library name and logo	Administration → Libraries, and the `OpacMainUserBlock` / `opacheader` blocks

The header, footer and navigation are covered in full in changing the Koha OPAC header, footer and navigation.

Why not just edit the theme files

You can. /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/ is on disk and writable by root, and a change there works immediately. It is also owned by the koha-common package, so the next upgrade overwrites it — and the customization disappears with no error, on a day chosen by your unattended-upgrades schedule rather than by you.

The preferences exist to make that impossible. They live in the database, so they are carried by koha-dump, restored with the instance, and survive every upgrade by construction. The rule worth adopting is simple: if a customization is not in the database, it is temporary, whether or not you meant it to be.

The same reasoning is why an OPAC redesign of any size is better done as a proper theme than as a thousand lines in a preference box — a text area with no version control is fine for fifty lines and unmanageable at five hundred.

It is not applying

What you see	What it usually is
Nothing changes at all	The preference was saved but the page is cached. Hard-reload (Ctrl+Shift+R), and restart Plack if it is enabled: `sudo koha-plack --restart library`.
The CSS appears in the page as text	`<style>` tags were pasted in. Remove them — Koha adds them.
Some rules apply, one does not	Specificity. A theme rule with a longer selector wins; make yours more specific rather than reaching for `!important`.
Works in the OPAC, not in staff	They are separate preferences. Staff CSS is `IntranetUserCSS`.
JavaScript does nothing	An earlier error stopped the script. Open the browser console — the first error is the real one.
It worked, then vanished after an upgrade	The change was made in a theme file on disk, not in a preference.

Share this article

Would rather not do this yourself? We do it as a service — and if you would rather it were already done, it is on Koha Cloud before you log in.

Koha OPAC customization See Koha Cloud