Skip to content

River Variables

Variables (aka 'CSS Custom Properties') are the centre of the River framework.

The /core/css/_variables.css file contains every variable available. At the time of writing, it contained 429 variables over 25 categories. A good way to understand how variables are handled is to look at this document.

Variable names freeze in CiviCRM 6.10

River's Variables changed names often between release in CiviCRM 6.0 and version 6.10, at which point they were locked. This is because the discussion about the best semantic structure for the variable names and the work of making the naming consistent, only happened after wider use.

From 6.10 onwards the goal is to not change or remove these variable names without a year or more's notice; less than that then both new and old names must work using aliasing. In other words these variable names are safe to build sub-themes, Streams and custom extensions around without fear of upgrades breaking themes.

Variable types

There are three types of variable: Primitive, Semantic and Component (this matches similar syntax used by Figma, Penpot and others):

  • Primitive variables are the most basic foundational elements that can be used as building blocks for other variables. They take the form of specific colours, prefixed with --crm-c- and specific lengths, prefixed with --crm-l-.
    For example: --crm-c-green-dark: #2e562e; or --crm-l-medium: 0.5rem;.
  • Semantic variables are mostly made up from Primitives and can have a meaning like 'error' or 'small' that's more descriptive than Primitives. Keeping this distinction lets a Stream decide that, say, Errors are yellow and Warnings are purple by pointing to a different primitive.
    For example: --crm-success-color: var(--crm-c-green-dark) or --crm-padding-small: var(--crm-l-small)
  • Component variables are sets of variables specific to an area of the user-interface, with the name of the component prefixed, e.g. --crm-alert, --crm-input or --crm-table. They can be raw values or use Primitive and Semantic variables. Often they will use Semantic variables, so that, for e.g. changing the colour for the semantic warning variable will update all component instances with a warning (buttons, notifications, alerts, etc). Many of the component categories (below) match css files in the core/css/components directory, such as accordion, alerts, buttons (prefixed --crm-btn), dialogs, form, icon, front, table, tabs.
    For example: ---crm-btn-success-bg-color: var(--crm-success-color).

Variable naming

Variables share prefixes, to make it easier to find related variables in the browser Inspector and when searching the code. Every variable is prefixed with --crm- to avoid any clashes with other variables used by the CMS or its themes. Primitive colour variables are prefixed with --crm-c-, primitive lengths with --crm-l- and front-end-only variables with --crm-f-. Component variable groups normally start with the name of the component.

Also noteworthy: -bg- stands for 'background', -ink- refers to a colour applied on a background, while for semantic and component variables, the property (e.g. colour or padding) is normally at the end. US spelling for 'color' or 'center' is used, to match CSS.

The goal with variable names is the following structure:

-crm-[component]-[variant]-[state]-[element]-[property]/[type]

Because this structure was applied retroactively after River was released this isn't applied 100% consistently, but it's the standard for new variables, and any future changes to variable names. For example:

  • --crm-form-block-border-radius (component: form; element: block; element: text; property: border radius)
  • --crm-tab-hover-bg-color (component: tab; state: hover; property: background-color)
  • --crm-alert-success-border-color (component: alert; variant: success; property: border-color)

Variable categories

The variables file is structured into multiple categories, roughly starting with Primitive, then Semantic, then Component variables:

  1. Colour names, Primitive colours, e.g. --crm-c-gray-900, --crm-c-blue and --crm-c-amber-light.
  2. Practical colours, Semantic colours, e.g. --crm-text-light-color, --crm-link-color.
  3. Background & borderss, e.g. --crm-page-bg-color normally set to --crm-paper, --crm-layer2-bg-color:, --crm-border, see Variable Patterns: background variables.
  4. Emphasis colours, e.g. --crm-primary-color, --crm-success-color. See Variable Patterns: auto generated.
  5. Shadows, for block and box shadows, e.g. --crm-shadow-block.
  6. Lengths, including primitives --crm-l-small-4 and semantic lengths like --crm-padding-small. Within the length primitives are some further defaults: --crm-l-xsmall, --crm-l-small, --crm-l-medium, --crm-l-reg (1rem), --crm-l-large to encourage a smaller range of defaults sizes.
  7. Type, e.g. --crm-font, --crm-font-size, --crm-link-decoration, --crm-heading-bg-color.
  8. Buttons, uses --crm-btn-. The first component, with 27 variables, from --crm-btn-box-shadow to --crm-btn-icon-spacing. The icon can have its own background colour and border.
  9. Tables, uses --crm-table-, e.g. --crm-table-header-border-bottom.
  10. Panels, uses --crm-panel, e.g. --crm-panel-head-margin.
  11. Accordions, for expanding regions, uses --crm-accordion for the .crm-accordion-bold pattern and --crm-accordion2 for the .crm-accordion-light style. --crm-accordion-transform describes what happens to the icon next to the details on expand, --crm-accordion-transition defines the animation on the icon during the expand.
  12. Alerts for on page alert regions, use --crm-alert, e.g. --crm-alert-padding, --crm-alert-info-bg-color.
  13. Form for form elements: --crm-form- defines the general form, --crm-input- defines input boxes and elements, --crm-fieldset for fieldset. E.g. --crm-form-block-box-shadow: var(--crm-shadow-block);, --crm-input-bg-image, --crm-fieldset-padding.
  14. Tabs, for general tab layouts, uses --crm-tabs, see Variable Patterns: tabs.
  15. Contact layout, for tabs on the Contact layout, uses --crm-contact. The tabs can be swapped from top to left position, see Variable Patterns: contact layout.
  16. Dialog, for modal popups, uses --crm-dialog, e.g. --crm-dialog-inner-shadow, --crm-dialog-body-bg-color
  17. Dashlet, for the dashlets on the home dashboard, uses --crm-dashlet.
  18. Button dropdowns, for contextual dropdown menus, uses --crm-dropdown.
  19. Notifications, for popup notification alerts (normally appear top right), uses --crm-notify.
  20. Icons, for alerts and notifications where an icon is set with CSS, uses --crm-icon.
  21. Form Builder UI, only has one variable at time of writing, --crm-fb-header-bg-color.
  22. Wizard, for the multi-step user-interface wizard (e.g. on CiviMail and import), uses --crm-wizard.
  23. Alpha filter, for the alphabetised list used to filter some contact searches, uses --crm-filter.
  24. Frontend, prefixed with --crm-f-, and assigned to load on selectors inside .crm-public for public-facing CiviCRM pages.
  25. Deprecated variables, where variables go before they're removed from River. Don't use these!