Skip to content

River Theme Framework

Introduction

River is a theme framework built on top of CiviCRM's theme/sub-theme framework. It started shipping with CiviCRM 5.79 and from CiviCRM 6.0 was the default theme for new installs and CiviCRM Standalone.

It has four sub-themes, known as Streams:

  • Minetta, the default, based on Greenwich, the default theme of CiviCRM for many years - and named after the river that runs under Greenwich, NYC.
  • Walbrook, based on the Shoreditch / the Island themes - and named after the river running under Shoreditch, London.
  • Hackney Brook, based on Finsbury Park - and named after the stream, you guessed it, near Finsbury Park, London.
  • Thames, based on Aah - and named after the river running near creator Rich "Artful Robot" Lott's base.

River introduced to CiviCRM Dark Mode for each of these four Streams, which can be controlled in Display Settings.

Streams, CSS-Variable led sub-themes

It's important to understand that while many sub-theme frameworks are designed to have lots of CSS in each sub-theme; River's Streams are designed to be made up primarily of CSS Custom Properties, refered to here as CSS variables.

You can include custom CSS in Streams, as well as images and fonts – just like any sub-theme system – but the framework is designed so that you don't need to. Preferably you just use the CSS variables.

There's a few reasons for this approach: as well as this making it much quicker to make sub-themes (hours not days), it should reduce the chances of changes to CiviCRM's code breaking sub-themes. As a Stream made up of only CSS variables it should survive future changes to markup and River's core CSS. A sub-theme made up of css classes, elements and IDs is much more brittle because markup changes create selectors, and break old selectors. A lot of the motivation in building River was to support changes to CiviCRM without risk of breaking themes.

It also reduces the size of sub-themes significantly: Shoreditch had 2.2mb of compressed CSS sitting on top of 418kb of CiviCRM's core and Bootstrap3's CSS.** The Island** is 2.7mb of compressed CSS on top. Walbrook (the Shoreditch/Island Stream) is 10kb of CSS sitting on top of 377kb of River's core css (including Bootstrap), less than 20% of the size. Dark mode is another 3kb on top - or 73 lines.

Getting Started

To enable or change a Stream, go to Administer > Display Settings and select one of the four Streams above for back-end.

Here you can also set dark mode handling: to always use light mode, to always use dark mode, or to inherit the browser/operating system's settings.

If you cannot see the four Streams in your Display Settings theme selection, and you are on CiviCRM 5.89 or later – check if the River Lea extension is enabled in extensions manager.

Proceed with caution when using River's Streams on public-facing pages

River's use in CiviCRM's backend has been extensively tested and is considered stable. However for public-facing pages there has been less testing, and there are potentially more combinations of different CMS themes and customisations. Therefore make sure any public-facing use is fully tested at multiple screen sizes. If problems appear, please discuss them in Mattermost UI channel or post bugs on Gitlab.