How to Customize the Koha OPAC Homepage

Yes, the Koha OPAC homepage is fully customizable — without touching any server files. Koha exposes a set of system preferences that inject HTML directly into specific zones of the homepage, giving you control over the welcome panel, top strip, right sidebar, and more. The changes take effect immediately after saving.

For basic branding updates — a welcome message, a featured collections list, a news item — the built-in preferences are sufficient. For anything more complex (consistent design across pages, mobile-friendly layouts, styled components), you’ll hit the tool’s limits quickly. This guide covers both what you can do natively and when a dedicated theming solution makes more sense.

Key System Preferences for the Koha OPAC Homepage

All preferences below live in Administration > Koha System Preferences > OPAC. In Koha 23.05 and later, some HTML content has moved to HTML Customizations (Administration > HTML Customizations) — check your version’s documentation if a preference isn’t where you expect it.

OpacMainUserBlock

This is the most prominent customization zone. It renders as a full-width panel in the center of the OPAC homepage, below the search bar. Use it for:

• A welcome message with your library’s name and hours
• A featured collections section (manual HTML cards or an unordered list)
• An embedded news box or RSS feed
• A promotional banner for an upcoming event

opacheader

The opacheader preference injects HTML into the very top of every OPAC page — not just the homepage. It’s ideal for a branded header strip, a system-wide announcement banner, or a logo lockup if your Koha theme doesn’t already provide one.

OpacNavRight

Renders as a sidebar column on the right side of the homepage. Useful for “What’s New”, a social media links block, or a library hours summary.

How to Access and Edit These Preferences

1. Log in to the Koha staff interface.
2. Go to Administration in the top menu.
3. Select Koha System Preferences.
4. Click the OPAC tab (or use the search box to find the preference by name).
5. Locate the preference, paste your HTML into the text area, and click Save all OPAC Preferences.

Changes go live immediately — there is no staging or preview step.

Practical Examples

Welcome message with hours:

<div class="welcome-block">
  <h2>Welcome to Greenfield Public Library</h2>
  <p>We're open Monday–Friday 9am–8pm, Saturday 10am–5pm.</p>
  <p><a href="/cgi-bin/koha/opac-page.pl?page=2">View all locations &rarr;</a></p>
</div>

Featured collections list in OpacMainUserBlock:

<h3>Featured Collections</h3>
<ul>
  <li><a href="/cgi-bin/koha/opac-search.pl?q=subject:mysteries">Mystery &amp; Thriller</a></li>
  <li><a href="/cgi-bin/koha/opac-search.pl?q=subject:local+history">Local History</a></li>
  <li><a href="/cgi-bin/koha/opac-search.pl?q=audience:children">Children's Room</a></li>
</ul>

Promo banner in opacheader:

<div style="background:#1a6b3c;color:#fff;text-align:center;padding:8px;">
  📚 Summer Reading Program runs June 1 – August 31. <a href="/cgi-bin/koha/opac-page.pl?page=5" style="color:#ffd700;">Sign up here</a>
</div>

Limitations of Native Homepage Customization

• Raw HTML in a textarea. There is no WYSIWYG editor, no drag-and-drop, and no component library. Every change is written by hand.
• No visual preview. You save, then switch to the OPAC tab in your browser to see the result. Iteration is slow.
• Changes go live immediately. There is no draft mode or scheduled publish. A typo in your HTML breaks the homepage right away.
• No version history. Koha does not track previous values of system preferences. If you overwrite a working config, recovery requires a database-level lookup.
• Style conflicts. Your custom HTML inherits Koha’s default CSS. Achieving a modern, branded look often requires significant inline styles or OPACUserCSS overrides that grow unwieldy over time.
• Per-branch limitations. Multi-branch libraries cannot easily show different homepage content per branch through these preferences alone.

When Theme Builder Is the Better Option

If you want more than a welcome message — a homepage with a hero image, card-based feature sections, an events grid, or a look that’s consistent from the homepage through to the patron account page — the native preference approach becomes a maintenance burden.

KohaSupport Theme Builder provides a purpose-built homepage layout system with visual components, mobile-responsive layouts, and design tokens that apply consistently across every OPAC page. You edit content in structured fields instead of raw HTML textareas, and changes can be previewed before going live.

See also: Koha Themes vs OPACUserCSS Hacks for a side-by-side comparison of approaches. For a guided Theme Builder path, start at the Theme Builder Documentation Hub and continue with How to Configure the Homepage in Theme Builder.

Frequently Asked Questions

Can I add images to the Koha OPAC homepage? Yes. Upload images to your web server or a CDN, then reference them with standard <img> tags inside OpacMainUserBlock or opacheader. Koha does not have a built-in media library, so you need to host images separately.

Will my edits survive a Koha upgrade? System preference values are stored in the database and survive upgrades. However, Koha upgrades occasionally reset a preference to a new default — always back up your HTML content before upgrading.

Can different branches show different homepage content? Not through OpacMainUserBlock alone — it is a global setting. You can use OPACUserJS to detect the current branch and swap content dynamically, but this requires JavaScript knowledge and ongoing maintenance. Theme Builder handles per-branch content natively.

What is the difference between OpacMainUserBlock and OpacNav? OpacMainUserBlock is the large center content area — the main canvas for homepage customization. OpacNav is the narrower left sidebar, typically used for navigation links. See How to Customize Navigation Menus in Koha for full details on nav preferences.

For the complete picture of every customization option in Koha, see the Koha Customization Guide.

Related: OPACUserCSS and OPACUserJS Guide · How to Modernize the Koha OPAC · Theme Builder Documentation Hub · How to Configure the Homepage in Theme Builder

Take Your Koha OPAC Further