Monthly Archives: March 2014

A New OPAC Theme: Bootstrap

As of Koha 3.14 the OPAC has a new default theme: Bootstrap. It’s a theme I developed with the intention of offering a flexible, modern, and responsive theme option for Koha libraries. It takes as its visual basis the CCSR theme, added in 3.10. However, it greatly expands the catalog’s mobile-friendliness over the CCSR theme.

The Bootstrap theme is so named because it uses the Bootstrap framework, a set of JavaScript and Cascading Style Sheet tools for use by web developers to quickly and easily add functionality to sites. Bootstrap helps web developers do things like add menus, dialogs, tooltips, etc. Bootstrap also brings some improved default styling to buttons and forms.

Like the CCSR theme, the Bootstrap CSS framework offers something called responsiveness. This means that when the size of your viewport (for instance, the browser window) changes, the layout of the page changes in response. With a desktop browser you can see this by resizing the browser window. Users with mobile devices of varying sizes will see a layout more closely tailored to the size of the screen on their device.

In the CCSR theme there is only one breakpoint. Breakpoints are the pixel dimensions at which the layout changes. When browsing a catalog which uses the CCSR theme, if the viewport size is below 700 pixels the layout changes to accommodate the smaller screen.

Bootstrap offers a few more breakpoints. If you’re reading this in a desktop browser you can view this demo page and resize your browser window to see the effects on the page layout. In Bootstrap there are three primary breakpoints, for large, medium, and small screens.

Koha’s new Bootstrap theme expands on these default breakpoints by adding a few more which are tuned to the layout of the OPAC.


The Bootstrap theme was designed to be just as flexible for customization as the old default theme. All the customizable regions are there. The same options are available for adding custom CSS and JavaScript. However, the responsive nature of the theme adds some new complications.

If you’re adding content to a region like opacheader or OpacMainUserBlock you’ll need to keep in mind that your content should respond comfortably to the same range of breakpoints that the rest of the catalog does. If you’re simply adding text this isn’t a problem because text flows naturally no matter the page width. If you’re adding something more complicated like images or navigation menus it will require some additional testing.

If you find your custom content is not flowing nicely at multiple screen sizes you can try tailoring that content with CSS using the same major breakpoints which are built into the Bootstrap theme:

[sourcecode language=”CSS”] @media only screen and (min-width: 0px) and (max-width: 390px){
/* Screens bewteen 0 and 390 pixels wide */
/* Add custom CSS here */
@media only screen and (min-width: 342px) and (max-width: 479px) {
/* Screens bewteen 342 and 479 pixels wide */
/* Add custom CSS here */
@media only screen and (min-width: 480px) and (max-width: 608px) {
/* Screens between 480 and 608 pixels wide */
/* Add custom CSS here */
@media only screen and (min-width: 608px) and (max-width: 767px) {
/* Screens between 608 and 767 pixels wide */
/* Add custom CSS here */
@media only screen and (min-width: 768px) and (max-width: 984px) {
/* Screens between 768 and 984 pixels wide */
/* Add custom CSS here */
@media only screen and (min-width: 984px) {
/* Screens above 969 pixels wide */
/* Add custom CSS here */

If you would like to get visual feedback in the Bootstrap OPAC about which media queries are being applied, add this HTML to the opacheader system preference:

[sourcecode language=”html”]

Some examples

One of the more common items to customize in the previous default OPAC theme was the logo. My first post here was on Customizing Koha 3’s OPAC logo. The Bootstrap theme no longer has an area designed specifically for a logo. The main search bar area takes up the full width of the screen. This makes it more adaptable to various screen sizes.


There is a Koha logo in the “nav bar” region at the very top of the screen which could be customized using CSS, but it’s quite small and disappears at narrower screen widths.

The opacheader region (customizable via system preferences) will probably be the primary customization option for adding logos, banners, custom top-level navigation, etc.

Image banner

A simple option is to add an image to the opacheader region. This is a simple option because the built-in CSS for images allows an image banner to naturally resize to match the browser width. This method uses the browser’s built-in image resizing algorithm.

In your opacheader system preference:

[sourcecode language=”html”] Your Library Name

The result is fully-adaptable to various screen sizes.

Tabbed navigation

As an example of some  custom content which might require more complex CSS customization at varying screen sizes let’s look at an example with tabbed navigation.  Here’s the code we’ll start with:


[sourcecode language=”css”] #opacheader {
padding : 10px 10px 0 10px;
border-bottom : 1px solid #666;
#opacheader ul {
margin-bottom : 0;
#opacheader li {
display: inline;
#opacheader li a {
font-size: 125%;
display: inline-block;
border : 1px solid #666;
border-bottom-width: 0;
padding : 5px 15px 5px 15px;
background-color : #FFF;
border-radius : 5px 5px 0 0;

In opacheader:

[sourcecode language=”html”] [/sourcecode]

At the default browser font size/zoom setting these tabs work with a viewport width down to about 607 pixels wide:


Below that width the tabs start to wrap in an awkward way:


Here’s where the use of CSS media queries can help us out. Let’s say we determine that the layout breaks at 600 pixels wide (a browser extension like Web Developer Toolbar can help us find the correct number). Let’s write a media query which targets a browser window which is narrower than 600 pixels wide:

[sourcecode language=”css”] @media only screen and (max-width: 600px) {
/* Screens below pixels wide */
#opacheader {
text-align : center;
#opacheader li a {
font-size : 110%;
border-bottom-width : 1px;
border-radius: 5px;
margin : 4px;

We append that CSS to the CSS already in OPACUserCSS and test:


Now the tabs are styled one way when the screen width is above 600 pixels, and another when the width is below 600 pixels.

I hope this example gives you a sense of what is possible when it comes to customization in the new theme. Planning your customizations for more than one screen width can be time-consuming, and lots of trial and error will be involved. The outcome, however, is a site which will be much more broadly usable.