Skip to content
Bess Sadler edited this page Mar 20, 2024 · 101 revisions

NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, please see the end of this page.

Blacklight is an open source Ruby on Rails "engine" that provides a basic discovery interface for searching an Apache Solr index, including fielded searching, applying and removing facet constraints, sorting and paginating through search results, and more. As an engine, Blacklight components are customizable via Rails (templating) mechanisms to meet the search and discovery needs of heterogeneous data, allowing different information displays for different types of objects.

Other out-of-the-box features include:

  • Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
  • A JSON API For searching and retrieving records
  • RSS and Atom feeds of search results
  • OpenURL/Z39.88 COinS support, allowing plugins like Zotero to easily extract data from the page.
  • OpenSearch and, a collection of simple formats for the sharing of search results.

About this guide

This wiki provides high-level documentation of Blacklight and supplements the inline code documentation (also available from RubyDocs). This wiki assumes you have prior experience with Ruby and Ruby on Rails. If you have no prior experience with either, there are some good free resources on the internet for learning Ruby, including:

And resources for learning Rails, including:

Additionally, you may want to review the official Apache Solr Tutorial, as the underlying search index and configuration provides and powers much of the Blacklight user experience but are outside the scope of this guide. This includes topics like how to index data into Solr, how to configure Solr request handlers, and the Solr schema format.


Each version of Blacklight may have specific requirements for underlying technologies and inherits some requirements from upstream software (like Rails, Solr, etc). As of Blacklight 7, these requirements are:

  • Ruby 2.5 or greater, including Ruby 3.0.
  • Rails 5.2 or greater, including Rails 6.0 and 6.1 (note that Rails has additional prerequisites, including Node.js, SQLite3, and Yarn)
  • Solr 8 or greater (which again has its own system requirements, including Java 1.8 or greater)

In general, Blacklight provides support for currently supported version of Ruby, Ruby on Rails, and related components, and is known to work with versions of Solr all the way back to Solr 1.4 (although some Blacklight features and functionality may require more recent versions)

Getting started

The quickstart guide will walk you through running Solr, building a new Rails application with Blacklight, and indexing a sample set of records. You can also start from a pre-generated Blacklight application.

Additional workshop materials are available for learning how to customize and extend the application.

Features and configuration

Blacklight provides out-of-the-box support for many types of search interactions through configuration, and with additional customization can be adapted to work with many types of data and user experience needs.

Blacklight configuration

A list of available Blacklight configuration options, and their default values, is available at blacklight/configuration.rb. In addition to the Blacklight-defined configuration discussed here, you may also add application-specific configuration (e.g. for controlling behavior in overridden partials) or plugin-specific configuration.

General configuration


Customizing behavior

There are many ways to override Blacklight's out-of-the-box user experience and search interactions because Blacklight is distributed as a Rails engine that resides within your own application. This means that most any customization can be done within your application by overriding Blacklight-provided behaviors without needing Blacklight to support specific configuration for less common or application-specific use cases. That said, this wiki has a directory of Blacklight plugins that has some types of functionality that is not in core Blacklight but is easily shared across multiple applications.

Customizing the UI

  • Theming: Overriding the Blacklight CSS
  • Pagination: Advice on how to customize pagination with Kaminari

Other Customizations

Other Plugins

  • There are lots of plugins and add-ons, documented here.

API documentation


Don't be scared to ask a question on the #blacklight channel in the Code4Lib Slack team. If you're not on Code4Lib Slack, you can request an invitation. This is the primary place where conversation takes place.

We appreciate you checking the documentation first and asking an educated question, but don't beat your head against the wall -- sometimes the existing documentation may be out of date and inaccurate.

There is also a Blacklight mailing list. In order to reduce spam, the first time you post your email will be held in a moderation queue, but as soon as your first message is approved your posts won’t be held for moderation any longer.

Contributing to Blacklight

Frequently asked Questions

Older Documentation

This wiki provides developer documentation for the main branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also:

Clone this wiki locally