Customising River¶

River was conceived to make it easier to restyle CiviCRM in a way that minimises the risk of breaking on upgrade. There's three methods:

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 buttons rounded corners, you could add to your CMS theme:

:root {
  --crm-btn-radius: 50%;
}

To apply this only to Contribution form pages, you could instead scope it:

.crm-contribution-main-form-block {
  --crm-btn-radius: 50%;
}

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 duplicate the 'empty' stream which contains the two _main.css and _dark.css files, then 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.

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.example.org/civicrm/admin/setting/preferences/display?reset=1&safe_css=1