Koha Solutions

OPAC & customization

How to customize the Koha OPAC: every place to change it

Library name, logo, favicon, contact details, header, navigation links, home page boxes, staff and opening-hours pages, news and events, a new arrivals slider, cover images, the record page, themes and plugins: where each one is changed in Koha, and what survives an upgrade.

By Babar Junaid

Published 2026-11-10 · Tested against Koha 26.05

Almost everything on the Koha OPAC is changed from the staff interface, with no server access: System preferences → OPAC for settings and CSS, and Tools for content (HTML customizations, Pages, News, Quote editor, Record display customizations). Use those first: they are stored in the database and survive every upgrade. Editing Koha's template files is the last resort, because a package upgrade overwrites them.

What you want to changeWhere
Library name in the top bar and the browser tabLibraryName preference (step 2)
The logoCSS in OPACUserCSS (step 3, and changing the Koha OPAC logo)
The little icon in the browser tabOpacFavicon preference (step 2)
Address, phone, email and opening hoursAdministration → Libraries + an OpacLibraryInfo HTML customization (step 2)
A library drop-down next to the search boxOpacAddMastheadLibraryPulldown preference (step 2)
A banner or strip under the top barTools → HTML customizations → opacheader
Your own search bar instead of Koha'sTools → HTML customizations → OpacCustomSearch
The footerTools → HTML customizations → opaccredits
Links in the menuHTML customizations: OpacMoreSearches, OpacNav, OpacNavBottom
Boxes in the left, centre or right of the home pageTools → HTML customizations → OpacNav, OpacMainUserBlock, OpacNavRight
A staff directory or opening-hours pageTools → Pages
News and eventsTools → News
Quote of the dayQuoteOfTheDay preference + Tools → Quote editor
A new arrivals slider on the home pageA public report + an HTML customization + OPACUserCSS/OPACUserJS
What a record's page showsRecord display customizations, or an XSLT file
Cover images on recordsSystem preferences → Enhanced content (step 11)
Open records in simple, MARC or ISBD viewBiblioDefaultView preference (step 11)
Colours, spacingOPACUserCSS
The font, or one font for English and another for Urdu, Arabic, Hindi, Tamil or BengaliFont files on the server + @font-face in OPACUserCSS: changing the font in the Koha OPAC
Every other display location (login instructions, results sidebar, cookie notice and more)HTML customizations
The page layout itselfA theme of your own (last resort)

Step 1: Start with the OPAC system preferences

Administration → System preferences → OPAC has ten sections, from Appearance to Authentication. Appearance holds the ones this article uses: LibraryName, OPACUserCSS, OPACUserJS, OpacFavicon, the three OPACXSLT…Display preferences, and opacthemes. Each one is saved with its own Save button and shows on the next page load: no restart.

Tools → HTML customizations, News and Pages only appear for staff with the Tools permission edit_additional_contents; a staff member without it does not see them in Tools at all. Each entry is written in an editor: by default the WYSIWYG one (preference AdditionalContentsEditor = TinyMCE). For HTML with classes, a form or a script, use the arrow next to New entry and pick New entry using text editor: a code editor that keeps your HTML as you typed it. Set AdditionalContentsEditor to CodeMirror to make it the default.

Step 2: Your library's identity: name, favicon and contact details

  • Library name. LibraryName is the text in the top bar and also the browser tab title: set to Kbverify Library, the tab read Kbverify Library catalog. Write the name only, no HTML.
  • Favicon (the icon in the browser tab). OpacFavicon takes a full address starting with https://, for example https://www.example.org/favicon.png. Left empty, Koha shows its own icon. Details, with the logo, in changing the Koha OPAC logo.
  • Address, phone, email, website. These come from Administration → Libraries → Edit, not from a preference. With OPACShowLibraries on Show (the default) the OPAC menu has a Libraries link (Contact when there is only one library) to /cgi-bin/koha/opac-library.pl, which shows them: a phone saved there appeared as Phone: +1 555 0100.
  • Opening hours or directions for one library: an HTML customization in OpacLibraryInfo, limited to that library. It shows on that library's page only.
  • A library drop-down in the search bar. OpacAddMastheadLibraryPulldown set to Add puts a list next to the search box, starting with All libraries, so a reader can search one branch. It appears only when there is more than one library.

Step 3: Change the logo and the header

The text in the top bar is the LibraryName preference. The Koha logo next to it is not an image tag: it is a CSS background on #logo (koha-green-logo.svg). So the logo is replaced with CSS. Upload your logo somewhere it has a public address (Koha's Tools → Upload, or your website), then add this to OPACUserCSS with your address and size:

OPACUserCSS
#logo { background-image: url("https://cdn.example.org/our-logo.png"); background-size: contain; width: 200px; } #logo a { width: 200px; padding-top: 50px; }

Response from a live run on Koha 26.05

width is the logo's width and padding-top its height. The library name stays in the page for screen readers. For a full-width banner under the top bar, use Tools → HTML customizations → New entry, display location opacheader, and put the image or text in Content. It shows on every page, directly under the top bar.

Koha has no menu editor. Links are HTML customizations, and the display location decides where they appear:

Display locationWhere the links show
OpacMoreSearchesThe row of links under the search box (next to Advanced search), on every page. Write each link as <li class="nav-item"><a href="/cgi-bin/koha/opac-page.pl?page_id=1">Opening hours</a></li>
OpacNavThe left column of the home page and most account pages
OpacNavBottomThe left column too, under OpacNav
OpacNavRightThe right column of the home page (step 5)
opacheaderUnder the top bar, on every page: use it for a full menu bar of your own
OpacCustomSearchReplaces Koha's whole search bar with your HTML. Your form must send the words to /cgi-bin/koha/opac-search.pl as q, or search stops working
opaccreditsThe footer, at the bottom of every page: address, copyright, links

Each entry can be limited to one library and has a version per language, so a branch can show its own links (a separate OPAC for each branch goes further). The footer and side panels are covered in the OPAC header, footer and navigation article.

Step 5: Add boxes to the left, centre and right of the home page

The OPAC home page has three columns, and each one is filled from an HTML customization. There is nothing to switch on: a column appears as soon as one of its locations has content.

Display locationWhere it shows
OpacNavLeft column, top. The left column only exists while OpacNav or OpacNavBottom has content
OpacNavBottomLeft column, under OpacNav
OpacMainUserBlockCentre, under the news and the quote of the day
OpacNavRightRight column, under the login box
  1. 1Go to Tools → HTML customizations → New entry.
  2. 2Pick the Display location from the table, and a Library: All libraries, or one branch if only that branch should show it.
  3. 3Give it a Title. It names the entry in the list only: neither OpacNav nor OpacNavRight prints it on the OPAC, so put the heading you want inside Content.
  4. 4Write the box in Content, in HTML. With more than one OPAC language, each language has its own tab; one left empty uses the Default text.
  5. 5Leave Publication date as today (a future date hides it until then) and save. It shows on the next page load.

A left box of links, for example, with the staff page from the next step as its first link (replace PAGE_ID with that page's number):

HTML customization (OpacNav), Content
<h2>Quick links</h2><ul>  <li><a href="/cgi-bin/koha/opac-page.pl?page_id=PAGE_ID">Our staff</a></li>  <li><a href="https://www.example.org/library">Library website</a></li></ul>

And an opening-hours box on the right:

HTML customization (OpacNavRight), Content
<h2>Opening hours</h2><p><strong>Mon-Fri</strong> 8:00-20:00<br><strong>Sat</strong> 9:00-13:00</p>

In the run, with both saved the home page switched to three columns. The centre narrows to make room, so keep side boxes short: a few links, a few lines. Anything longer belongs on a page of its own.

Step 6: Add a staff page or an opening-hours page

A page of your own, such as a staff directory, rules, or opening hours with holidays, is made in Tools → Pages. Koha gives it its own address and shows it inside the OPAC's header and footer. Every option of the tool is in making a custom page in the Koha OPAC.

  1. 1Go to Tools → Pages → New entry.
  2. 2Set Display location to OPAC (the choices are Staff interface and OPAC, Staff interface and OPAC), and Library to All libraries or one branch.
  3. 3Write the Title: it becomes the page's heading. Put the page itself in Content, for example the staff table below.
  4. 4Save. The list shows an OPAC link next to it: the page's address is /cgi-bin/koha/opac-page.pl?page_id= and its number.
  5. 5Link to it: from a left box (step 5), or from the row under the search box with an OpacMoreSearches entry (step 4).
Pages entry "Our staff", Content
<table class="table">  <tr><th>Name</th><th>Role</th><th>Email</th></tr>  <tr><td>A. Librarian</td><td>Chief librarian</td><td>chief@example.org</td></tr>  <tr><td>B. Assistant</td><td>Circulation desk</td><td>desk@example.org</td></tr></table>

class="table" gives it the OPAC's own table style. For photos, add an <img> per person with an address the page can load and a short alt text. A page set to Staff interface, or limited to another library, sends OPAC visitors to the 404 page, so check the display location if a link "does not work".

Step 7: Show your news and events

Koha has a news module and no events module. News items appear on the OPAC home page, newest first, each with "Published on" and its date, plus an RSS feed of them (opac-news-rss.pl). An event is a news item with an end date.

  1. 1Go to Tools → News → New entry.
  2. 2Display location: OPAC (or Staff interface and OPAC for staff too). Library: All libraries, or one branch.
  3. 3Title (required) and Content.
  4. 4Publication date: the day it should appear. A date in the future keeps it hidden until then, so an event can be announced a week before.
  5. 5Expiration date: for an event, the day of the event. It still shows on that day and disappears from the home page the day after.
News item "Library workshop: finding journal articles", Content
<p><strong>Thursday 3 December, 14:00, Main reading room.</strong> A one-hour session on finding journal articles. Free, no booking.</p>
  • Order is by publication date, newest first. Appear in position does not change the order on the OPAC: in the run, an item set to position 1 still came under a newer item set to position 2. To pin an item to the top, give it the newest publication date.
  • An expired item is not deleted. Its own link (opac-main.pl?news_id=) still opens it, as the editor's hint says: "News will still be accessible by direct URL if expired." Delete it if it must disappear completely.
  • With several branches, the OpacNewsLibrarySelect preference adds a "Display news for:" list above the news.
  • For a long programme of events, one page in Tools → Pages called Events, linked from a left or right box, is easier to keep up to date than many news items.

Step 8: Show a quote of the day

  1. 1In System preferences, search for QuoteOfTheDay and tick OPAC (and staff interface if you want it there too). It is empty on a new Koha, so no quote shows anywhere.
  2. 2Go to Tools → Quote editor. Add quotes one by one with New quote (Source and Text), or load a CSV of them with Import quotes.

It changes every day by itself; there is no setting or cron job for it. The first visit of the day picks a quote at random and stamps it with today's date (the Last display column in the Quote editor). Every visit that day shows that same quote. The next day nothing is stamped with the new date, so Koha picks another. The choice is random, so a quote can come back before all the others have been shown. With only a few quotes that happens often, which is why a list of at least a few dozen works best.

Step 9: Add a new arrivals slider

Koha has no built-in slider. The upgrade-safe way is four small pieces, all in the staff interface. First, a report that lists the newest books. In Reports → Create from SQL, save this, then edit it and tick Public (only public reports can be read by the OPAC):

SQL report
SELECT b.biblionumber, b.title, b.author, MAX(i.dateaccessioned) AS addedFROM items iJOIN biblio b ON b.biblionumber = i.biblionumberWHERE i.withdrawn = 0 AND i.itemlost = 0 AND i.dateaccessioned IS NOT NULLGROUP BY b.biblionumber, b.title, b.authorORDER BY added DESC, b.biblionumber DESCLIMIT 20

Response from a live run on Koha 26.05

It sorts by the date the copy was accessioned, not the date the record was created, so a batch of old records imported last week does not fill the slider. Withdrawn and lost copies are left out. Note the report's number (the id in its address). Its results are now at /cgi-bin/koha/svc/report?id=number&annotated=1 as JSON. The LIMIT decides how many books come back; without one, Koha returns only 10 (the SvcMaxReportRows preference).

Second, the place on the page: an HTML customization in OpacMainUserBlock (the middle of the home page) with this content:

HTML customization (OpacMainUserBlock)
<h2>New arrivals</h2><div id="new-arrivals" class="new-arrivals"></div>

Response from a live run on Koha 26.05

Third, the look, added to OPACUserCSS: a row of cards that scrolls sideways and snaps to each one.

OPACUserCSS
.new-arrivals { display: flex; gap: 1rem; overflow-x: auto; scroll-snap-type: x mandatory; padding-bottom: .5rem; }.new-arrivals a { flex: 0 0 10rem; scroll-snap-align: start; border: 1px solid #ddd; border-radius: 6px; padding: .75rem; }

Response from a live run on Koha 26.05

Fourth, the code that fills it, added to OPACUserJS. Replace REPORT_ID with your report's number. jQuery is already loaded on every OPAC page.

OPACUserJS
$(function () {  var box = $("#new-arrivals");  if (!box.length) return;  $.getJSON("/cgi-bin/koha/svc/report?id=REPORT_ID&annotated=1", function (rows) {    $.each(rows, function (i, r) {      $("<a>").attr("href", "/cgi-bin/koha/opac-detail.pl?biblionumber=" + r.biblionumber)        .text(r.title + (r.author ? " / " + r.author : "")).appendTo(box);    });  });});

Response from a live run on Koha 26.05

Reload the OPAC home page: the row fills with one card per book, newest first, each linking to the book's page. To show covers, add an <img> to each card from whichever cover source your OPAC already uses.

The slider is stuck, or shows books that are gone

Koha keeps a public report's JSON in its cache (memcached) for the report's Cache expiry, 300 seconds by default. Until it expires, every visitor gets the saved copy. We tested both symptoms on Koha 26.05.02: a book added after the first request did not appear, and a deleted book stayed in the slider, until the cache was cleared. Then the deleted book was gone and the new one was first.

SymptomFix
New books take minutes to appear, or a deleted book still showsNormal for up to the cache expiry. To make it shorter, open the report in Reports → Use saved, Edit, and lower Cache expiry (seconds). To clear it at once, restart memcached (sudo systemctl restart memcached)
It still shows old books after hoursThe report sorts by the wrong date. Sort by items.dateaccessioned, as above, not biblio.datecreated: imported records get the import date. Copies with no accession date are left out
Withdrawn or lost books appearThe report has no withdrawn = 0 AND itemlost = 0
Always exactly 10 booksThe report has no LIMIT, so SvcMaxReportRows (10) applies. Add one
The slider is emptyThe report is not Public (the address answers "Sorry this report is not public"), or REPORT_ID was not replaced. Open the svc/report address in the browser to see which
The cards do not moveThe CSS is missing from OPACUserCSS; the row needs display: flex and overflow-x: auto

Step 10: Change what a record's page shows

For adding something, use Tools → Record display customizations. An entry with display location OPACDetailPage is added under the record's description on its page; OPACResultsPage and OPACListPage do the same for search results and lists. The content can use the record: [% record.title %] printed each book's own title in our test. Nothing here touches Koha's files. More in changing what the Koha OPAC record page shows.

To change the description itself, Koha uses an XSLT file: OPACXSLTDetailsDisplay (and the Results and Lists ones) say default, or a path to your own file. Copy the default file somewhere the package does not own, then fix one line: the copy imports MARC21slimUtils.xsl by a relative name, and from another folder that fails. The record page then shows no description at all, and plack-opac-error.log says xsl:import : unable to load …/MARC21slimUtils.xsl.

Terminal
$ sudo mkdir -p /usr/local/share/koha-custom$ sudo cp /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/MARC21slim2OPACDetail.xsl /usr/local/share/koha-custom/$ sudo sed -i 's#"MARC21slimUtils.xsl"#"/usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/MARC21slimUtils.xsl"#' /usr/local/share/koha-custom/MARC21slim2OPACDetail.xsl$ grep -n 'xsl:import' /usr/local/share/koha-custom/MARC21slim2OPACDetail.xsl10:    <xsl:import href="/usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/MARC21slimUtils.xsl"/>
Response hidden (1 line)
Showing the response of this command only

Response from a run on Ubuntu 24.04, koha-common 26.05.05

Edit your copy, then set OPACXSLTDetailsDisplay to /usr/local/share/koha-custom/MARC21slim2OPACDetail.xsl. After an upgrade, compare your copy with the new default: a changed default is not merged into it.

Step 11: Cover images, summaries and the default record view

Covers are switched on in Administration → System preferences → Enhanced content. None of them is on in a new Koha, and each works differently:

PreferenceWhere the cover comes from
OpenLibraryCoversOpen Library, by the record's ISBN. Free, nothing to sign up for. Turned on, a record with an ISBN got an Open Library cover box
GoogleJacketsGoogle Books, by ISBN
OPACAmazonCoverImagesAmazon, by ISBN
OPACLocalCoverImagesImages you upload yourself, stored in the Koha database: uploading cover images in bulk

A record without an ISBN gets no cover from the first three. Which sources still answer, and what to do when covers do not show: Koha cover images by ISBN. To serve your own images from a bucket: cover images from an S3 or R2 bucket.

A summary needs no service: a record with a 520 field shows it on its OPAC page as Summary:, with every enhanced content preference off. Fill 520 when cataloguing and the OPAC shows it.

BiblioDefaultView (OPAC preferences) decides which page a search result opens: in simple form (opac-detail.pl, the default), in their MARC form (opac-MARCdetail.pl) or as specified in the ISBD template (opac-ISBDdetail.pl). Whichever you pick, the record's page keeps its MARC view link, so a reader can still switch.

Step 12: Your own theme: the last resort

When a change cannot be made any other way, make a theme folder of your own instead of editing bootstrap. A folder in the OPAC template directory with an en folder inside appears as a choice for opacthemes. It needs only the templates you change: for every other page Koha falls back to the theme in OPACFallback (bootstrap). It does not fall back for CSS and JavaScript, though. A theme folder with only templates loads no opac.css (the log says File not found : css/opac.css, then js/basket.js and others), so its pages are unstyled. Link them to bootstrap's: To install a theme someone gives you, see installing a new theme in the Koha OPAC.

Terminal
$ cd /usr/share/koha/opac/htdocs/opac-tmpl$ sudo mkdir -p mytheme/en/modules$ sudo cp bootstrap/en/modules/opac-main.tt mytheme/en/modules/$ cd mytheme$ sudo ln -s ../bootstrap/css css$ sudo ln -s ../bootstrap/js js$ sudo ln -s ../bootstrap/images images$ ls -ltotal 4lrwxrwxrwx 1 root root   16 Nov  5 15:33 css -> ../bootstrap/cssdrwxr-xr-x 3 root root 4096 Nov  5 15:33 enlrwxrwxrwx 1 root root   19 Nov  5 15:33 images -> ../bootstrap/imageslrwxrwxrwx 1 root root   15 Nov  5 15:33 js -> ../bootstrap/js$ find /usr/share/koha/opac/htdocs/opac-tmpl/mytheme -name '*.tt'/usr/share/koha/opac/htdocs/opac-tmpl/mytheme/en/modules/opac-main.tt
Response hidden (6 lines)
Showing the response of this command only

Response from a run on Ubuntu 24.04, koha-common 26.05.05

Edit the copied template, then set opacthemes to mytheme. The folder belongs to no package, so an upgrade leaves it alone; but the templates you copied stay at the old version while bootstrap's move on. After each upgrade, compare them with the new bootstrap ones.

Step 13: Plugins

A Koha plugin can add to every OPAC page: the OPAC calls each enabled plugin's opac_head (inside the page head) and opac_js (at the end of the page). Plugins are off on a new install; see turning plugins on and installing a plugin that changes the OPAC. A plugin runs code on your server, so install only ones you trust, and test each Koha upgrade with it.

A private OPAC, or a maintenance page

  • OpacPublic set to Disable: every OPAC page asks visitors to log in first (Log in to your account).
  • OpacMaintenance set to Show: every OPAC page shows System maintenance instead. An HTML customization in OpacMaintenanceNotice replaces that text with your own.
  • To switch the OPAC off completely, or hide only some of it: turning the Koha OPAC off or making it login-only.

What survives an upgrade

On a package install, Koha's own templates and stylesheets belong to the koha-common package, and an upgrade replaces them. A folder you add belongs to nobody:

Terminal
$ dpkg -S /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/opac-main.ttkoha-common: /usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/modules/opac-main.tt$ dpkg -S /usr/share/koha/opac/htdocs/opac-tmpl/mythemedpkg-query: no path found matching pattern /usr/share/koha/opac/htdocs/opac-tmpl/mytheme
Response hidden (2 lines)
Showing the response of this command only

Response from a run on Ubuntu 24.04, koha-common 26.05.05

ChangeAfter an upgrade
System preferences, HTML customizations, Pages, News, quotes, record display customizations, reportsKept: they are in the database
OPACUserCSS / OPACUserJSKept, but a rule aimed at Koha's own markup can stop matching when the markup changes
Your own XSLT file or theme folderKept, but based on the old version: compare it with the new default
Edits to files in bootstrapLost: the package overwrites them
PluginsKept, but a plugin may not support the new Koha version yet

Why there are so many places

Koha grew its customization points one at a time. Header, footer and panel texts used to be system preferences and moved to HTML customizations so they could differ per library and per language; custom pages and record display customizations came later still. Older guides, and many forum answers, still point at preferences that no longer exist or tell you to edit template files. The database-stored options are the ones that keep working, which is why this article lists them first.

Tested on live Koha 26.05.02

Passed all 80 checks · Read the run log

Koha release
26.05.02
System
Debian 13 (trixie)
Setup
Official Koha test container (koha-common commands). A command that needs systemd or a firewall says where it ran.
Source read at
Koha commit d3fc229
Earlier live checks (2)
  • , Koha 26.05.02 (commit d3fc229): all 62 claims held. Read the run log
  • , Koha 26.05.02 (commit d3fc229): all 47 claims held. Read the run log
Verified against the Koha source (28 files)

The label under each command says where its response came from; a command with no label was not run live. How we test and which standards we follow.

Share this article

Want the OPAC to look like your library without touching Koha's files? Tell us what you have in mind and we will build it the upgrade-safe way.

Want your staff trained on this? We teach it hands on with a live Koha, online or at your library. Ask about staff training