Koha System

How to Use OPACUserCSS and OPACUserJS in Koha

Learn how to use OPACUserCSS and OPACUserJS system preferences in Koha to inject custom CSS and JavaScript into every OPAC page. Includes practical examples and limitations.

January 15, 2025 6 min read

OPACUserCSS and OPACUserJS are Koha system preferences that inject custom CSS and JavaScript into every page of the OPAC (public catalog). Whatever you enter in these fields is output globally — OPACUserCSS inside a <style> tag in the page <head>, OPACUserJS inside a <script> tag near the closing </body>. They are the primary way librarians and developers style the Koha OPAC without modifying server-side template files.

This guide explains what each preference does, how to use them correctly, and where their limits lie. For broader context on all the customization tools Koha provides, see the Koha Customization Guide.

Where to Find OPACUserCSS and OPACUserJS

Go to Administration → System Preferences → OPAC in the Koha staff interface. Both preferences are in the “Appearance” section. Each is a free-text area — paste your CSS or JavaScript directly into the field and save. Changes take effect on the next page load; no server restart is required.

OPACUserCSS

OPACUserCSS accepts standard CSS. You write rules exactly as you would in an external stylesheet — selectors, properties, values. Koha outputs this verbatim inside a <style> tag, so it applies to every OPAC page.

What it controls

Any element rendered in the OPAC HTML can be targeted. The most commonly overridden areas:

Navigation bar — .navbar-fixed-top, .navbar-brand
Search form — .opac-main-search, #searchform, .input-group
Results list — .search-results, .result-title, .result-info
Sidebar — #facets, .facet-label
Footer — #opac-footer, .container footer

Practical example: change the brand color

If you want to replace Koha’s default blue navbar with your library’s green, add:

.navbar-fixed-top {
  background-color: #2e7d32 !important;
}

.navbar-fixed-top .navbar-brand {
  color: #ffffff !important;
}

a {
  color: #2e7d32;
}

a:hover {
  color: #1b5e20;
}

If you want to hide the “library card number” label on the login form:

label[for="userid"] {
  display: none;
}

Note the use of !important in many cases — Bootstrap’s default specificity can outrank your rules without it.

OPACUserJS

OPACUserJS accepts JavaScript (including jQuery, which is already loaded on every OPAC page). Koha wraps your code in a <script> tag placed before </body>, so the DOM is fully available when it runs.

Common uses

Hide elements you cannot remove via CSS alone:

$(document).ready(function () {
  // Hide the "My Lists" tab in patron account
  $('a[href*="virtualshelves"]').closest('li').hide();
});

Add Google Analytics (GA4):

$(document).ready(function () {
  var script = document.createElement('script');
  script.src = 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX';
  script.async = true;
  document.head.appendChild(script);
  window.dataLayer = window.dataLayer || [];
  function gtag(){ dataLayer.push(arguments); }
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
});

Inject a simple cookie notice:

$(document).ready(function () {
  if (!localStorage.getItem('cookie_notice_dismissed')) {
    $('body').prepend('<div id="cookie-notice" style="background:#333;color:#fff;padding:10px;text-align:center;">This site uses cookies. <a href="/privacy" style="color:#aef;">Learn more</a> <button onclick="localStorage.setItem(\'cookie_notice_dismissed\',\'1\');this.parentNode.remove()">OK</button></div>');
  }
});

Library-Level CSS/JS Overrides (Koha 23.11+)

Koha 23.11 introduced per-branch CSS and JavaScript. In the staff interface, go to Administration → Libraries, edit a branch, and you will find UserCSS and UserJS fields. These inject additional CSS/JS only when a patron is logged in and associated with that branch, or when that branch is selected as the active library.

This allows multi-branch systems to give each location a distinct look — for example, a children’s branch can have a different color scheme — without affecting the default OPAC used by unaffiliated visitors. Branch-level overrides stack on top of the global OPACUserCSS/OPACUserJS, so you only need to write the differences.

Limitations to Be Aware Of

OPACUserCSS and OPACUserJS are powerful but have real structural limits:

No visual editor. You write raw CSS/JS with no preview. Mistakes go live immediately.
No rollback. Koha does not version control these fields. If you overwrite a working CSS block, it is gone unless you kept a separate backup.
Changes are immediate. Unlike a staging/preview workflow, every save is live to patrons.
Upgrade fragility. Koha’s HTML class names and element structure change between versions. A rule that targets .opac-main-search may break or do nothing after a version upgrade.
Cascade conflicts. Global OPACUserCSS and branch-level UserCSS can conflict. Specificity wars with Bootstrap selectors are common.
Requires CSS/JS knowledge. There is no guiding structure — you need to inspect the OPAC source yourself, identify the right selectors, and test in a browser.

When Koha Theme Builder™ Is the Better Option

If your goal is a fully branded OPAC — custom layout zones, typography, homepage content blocks, and a look that survives Koha upgrades — OPACUserCSS becomes a maintenance burden rather than a solution.

KohaSupport Theme Builder takes a different approach: structured design tokens, pre-built theme families, and a preview workflow that decouples your design from Koha’s internal class names. When Koha’s HTML changes in an upgrade, the theme is tested and updated centrally — you do not need to audit hundreds of CSS selectors yourself.

For a full comparison, see Koha Themes vs OPACUserCSS Hacks.

Frequently Asked Questions

Is it safe to use OPACUserCSS and OPACUserJS? Yes, for experienced CSS/JS developers. The risk is operational, not security-critical — bad CSS breaks layout, bad JS can break page functionality. Always test in a staging Koha instance before applying to production.

How do I test changes before they go live? Open your browser’s developer tools and paste your CSS into the “Styles” panel for live preview. Only commit to OPACUserCSS once you’re satisfied. For JavaScript, paste into the browser console first.

Can I use OPACUserCSS on a multi-branch system? Yes. Global OPACUserCSS applies everywhere. From Koha 23.11+, branch-level UserCSS lets each branch override specific rules. See the library-level overrides section above.

What if my CSS conflicts with Koha’s Bootstrap base? Increase specificity or use !important strategically. For recurring conflicts, switching to a structured theme approach (see Theme Builder) eliminates most of these because theme CSS is scoped and built with Koha’s actual output in mind.