River Lea Theme Framework¶

Introduction¶

CiviCRM 6 introduced a new theme framework for CiviCRM built on top of the existing theme engine. It is split between a core-layer that interacts with CiviCRM and a sub-theme layer called 'Streams' for individual styles and makes extensive use of CSS Custom Properties or CSS Variables. Each Stream introduces a dark-mode variation.

Streams¶

CiviCRM 6 includes four Streams, and a fifth 'empty' example Stream:

Minetta, based on Civi's historic 'Greenwich' theme (named after the river that runs under Greenwich, NYC).
Walbrook, based on Shoreditch / The Island themes (named after the river that runs under Shoreditch, London).
Hackney, based on the Finsbury Park theme (named after the river that runs nearby).
Thames, based on the Aah theme (named after the river that runs close to creator Artful Robot's office).

Getting Started¶

To enable or change a Stream, go to Administer / Display Settings and select a Stream above for back-end (front-end is not officially supported yet, use at own risk).

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.

Safe Mode¶

Just in case dynamic edits to your stream make your site unusable, you can enable a "safe mode" by adding safe_css=1 to your url parameters.

E.g. to open the display preferences page and change your theme, go to https://my.site.org/civicrm/admin/setting/preferences/display?reset=1&safe_css=1

Structure¶

The majority of the Riverlea extension is a layer of core CSS, which styles CiviCRM markup based on the value of a number of CSS variables.

Core theme¶

The underlying CSS for the framework is located in the /core/ directory of the extension (ext/riverlea/core).

The list of all core CSS variables with their default values can be found at core/css/_variables.css.

CSS files are located:

In the core/css directory are theme files marked with an underscore:
- core/css/_base.css – resets, basic type, colours, links, positioning
- core/css/_bootstrap.css – a Bootstrap subset
- core/css/_cms.css – resets and fixes specific to different CMSs
- core/css/_core.css - links to the UI components in the components directory:
- core/css/_fixes.css - CSS that’s necessary for now but one day could go.
- core/css/_variables.css - a list of all base variables
core/css/civicrm.css - a functional file that loads _base.css, _cms.css, _core.css and _fixes.css from above.
in the core/css/components directory are reusable UI elements, such as _accordions and _tables.css linked to by _core.css.
other files here without underscore (admin.css, api4-explorer.css, contactSummary.css etc) override CiviCRM's core CSS directory with files of the same name that are called by templates to only load in certain parts of Civi. E.g. dashboard.css loads on the CiviCRM main dashboard, and no-where else.
three directories: core/css/org.civicrm.afform-ang for Afform output, core/css/org.civicrm.afform_admin-ang for FormBuilder and core/css/org.civicrm.search_kit-css for SearchKit replace css files in core Civi extensions.

Streams¶

Each stream in the extension has a subdirectory under streams which primarily contains CSS files for the stream:

a _variables.cssfile. These will overrule any variables in the core list above.
a _dark.css if darkmode is supported.
A stream could also include images and other CSS files, which can be loaded from the _variables.css file as an import.

Each stream also has a Managed Record file which is used to "install" the stream. These are found in the managed directory.

Fonts¶

Fonts are located in the /fonts/ directory outside of the core and streams directories. River Lea includes two WOFF2 web Font Families:

Inter: Regular, Italic and 600/Bold.
Lato: Regular, Italic, 700/Bold and 700/Bold Italic.

Walbrook uses Inter, and Thames uses Lato: both load their fonts via @font-face in their civicrm.css file.

Customising¶

RiverLea was conceived to make it easier to restyle CiviCRM in a way that minimises the risk of breaking with upgrades. There's three methods to customise RiverLea:

With CSS Variables in your CMS theme
Add a custom CSS snippet in an extension
Through a custom Stream

1. With CSS Variables in your CMS theme¶

For instance, to give all contribution page buttons rounded corners, you could add to your CMS theme:

--crm-btn-radius: 2rem;

2. Add a custom CSS snippet in an extension¶

You can override variables by listening to hook_civicrm_alterBundle:

function my_ext_civicrm_alterBundle(CRM_Core_Resources_Bundle $bundle) {
  if ($bundle->name === 'coreResources') {
    $riverleaOverrides = <<<CSS
      :root {
        --crm-c-primary: green;
      }
    CSS;
    # weight should override river.css
    $bundle->addStyle($riverleaOverrides, ['weight' => 200]);
  }
}

3. With a Stream extension¶

New streams can be provided by extensions using CiviCRM's Managed Entity system. This is the same mechanism as can be used for packaging SearchKits, CustomFields, ContactTypes etc.

If not adding to an existing extension, follow the docs to create one.

Enable the mgd-php mixin in your extensions info.xml

  <mixins>
    <mixin>menu-xml@1.0.0</mixin>
    <mixin>mgd-php@1.0.0</mixin>
    ...
  </mixins>

Copy the template *.mgd.php from the docs folder of this extension into your extension's managed folder (create the managed folder if it doesn't exist). Remove the .template part so the file extension is *.mgd.php.
Update the use CRM_riverlea_ExtensionUtil line for the equivalent from your extension.
You can add variable declarations directly to the vars and vars_dark keys in the *.mgd.php file.
If you want to write your own CSS, you can create main.css and dark.css files in your extension, and set the css_file and css_file_dark properties of your Stream to point to them. It's best to use variable declarations as much as possible to maintain compatibility with future versions of CiviCRM.

For a working example, see the Deptford Creek extension.