Exploring CivCRM 6's new theme framework, River Lea

After 17 years of shipping with the Greenwich theme, the release of CiviCRM 6 last month brought to new installs a new default theme, Minetta, named after the river running under Greenwich, New York. But Civi 6 didn't mark the arrival of just one new theme; it shipped with four themes: Minetta, Walbrook, HackneyBrook and Thames.

Most significantly for CiviCRM developers, under the hood of these four themes is a new theme framework, River Lea. The new themes are actually sub-themes of River Lea, which is designed to make theming faster, more flexible, and future-proof, while opening up much easier customisation in the future.

---

Meet the Four “Streams” of River Lea

The River Lea framework introduces four distinct sub-themes—known as streams, because they branch off the CSS cascade downstream from 'River Lea'. Each is a modern, more accessible revamp of familiar designs, and is named after existing waterways.

So it took nearly two decades to release a new theme, and then, like buses, four arrive at once. Seems a bit keen! But there’s a good reason…

---

River Lea is a framework, not just a theme

CiviCRM’s markup is nearly 20 years old, and it shows. Over that time, it's accumulated a mix of HTML patterns, JavaScript frameworks, CSS techniques, and design approaches. Building a modern theme that works across all of that complexity is tough—and by the time it’s done, it might already look dated.

FormBuilder and SearchKit are Civi's central projects to modernise all of its markup, but there's so much of CiviCRM to migrate this is taking time. In the meantime Civi themes need to support both legacy and modern markup.

So when core team's Josh Gowans first suggested building a new theme for CiviCRM I approached Rich Lott to come up with a solution that would also help the bigger task of making CiviCRM's UI more accessible, mobile/tablet responsive and modern. We came up with a broader plan ("DINO"), built around documenting CiviCRM markup patterns to support the work of modernising them, with a new theme to support the process. But once we started modernising the markup of accordions in Civi – removing old JavaScript and making them accessible – we realised how easy it is to break themes, putting a huge cost on modernisation. We need a solution for all the popular CiviCRM themes.

Our goal was to simplify customisation, speed up development, and make it easier for Civi to fit into any website’s style. The result? A new middle layer sitting between CiviCRM core and a set of new, tiny sub-themes built to reflect the most popular Civi themes.

---

The power of CSS Variables

At the heart of River Lea is a lightweight sub-theme layer made almost entirely from CSS variables (also known as CSS Custom Properties). These are like variables in any programming language—you define them once, then reuse them across your design. This has some huge benefits:

• Want to change button colors, borders, shadows, or font styles? Just tweak a few variables, and they'll cascade across all the appropriate parts of Civi. If you change the variable `--crm-btn-roundness`, every button in Civi will shift between square and fully rounded corners.
• If you want to integrate CiviCRM in another design - perhaps an intranet, another CMS, or a front-end UI that's very different to Civi's look and feel, you can do this entirely by adding a new set of CSS variables further down the cascade: no need to rewrite or add lots of custom CSS.
• Updates to CiviCRM core, once implemented by RiverLea core will cascade automatically through all sub-themes, removing the risk of breaking the interface when Civi core is improved or introduces new features and layouts.

The result is a compact sub-theme layer – with just 15–30kb of CSS, compared with several megabytes for the biggest CiviCRM theme being replaced – underpinned by a powerful and flexible core theme.

These sub-themes are relatively easy to create yourself, and there's work underway by Ben Walpole to turn them into Civi entities so that a full customiser could make it even easier to quickly make new sub-themes

---

One More Thing: Dark Mode.

Finally, facilitated by the power of CSS Variables: each of the four new themes ships with a dark mode for those who want to save energy, screen-glare, or just look more like hacker in a movie. Ben added a controller to Display Settings, allowing users to chose between:

• Always Light mode
• Always Dark mode
• Auto mode (based on browser / operating system settings)

This meant we effectively released eight new Civi appearances—not four! This has it's own challenge when it comes to testing; Tim Otten developed a multi-theme testing extension 'ThemeView' to help, which has since been merged into the ThemeTest extension.

---

How to Get River Lea

• New installations of CiviCRM already use River Lea by default.
• Existing installs can upgrade and select one of the new themes from the admin panel. If you're using custom extensions, you should test them for compatibility, especially on the front end.
• Front-end caution advised: Be extra careful when enabling River Lea on front-end interfaces. With the huge variety of possible setups and extensions, thorough user testing is essential.

---

Help Us Improve!

If you spot any bugs or inconsistencies, please post an issue on GitLab. We’re keeping a close eye on community feedback and can roll out fixes quickly.

---

I'd like to thank the Academy…

This project wouldn’t have been possible without the amazing support of many people. Firstly Rich Lott / @artfulrobot - who helped conceive the original approach, provided feedback, criticism and encouragement throughout the project and delivered the beautiful Thames theme. And then @guillaume_allinappli, @ufundo, @haystack, @bradleyt, @tapash, @babu, @nadaillac, @hwessinx, @kurund, @rebeccatregenna, @bgm, @aydun, @jgaunt, @mattwire, @michaelmcandrew, @luciano_s, @monish.deb, @peter.reck, @thomasrenner & anyone else I've forgotten. Special thanks to @gibsonoliver for pushing this forward when it had lost momentum a few years back, and @josh, @eileen and the rest of core team for their backing – and finally anyone who donates to CiviCRM LLC, which allows initiatives like this to happen.

River Lea was around a year in the making, and we’re thrilled to see it out in the wild. Our hope is that this framework lays the foundation for faster, more beautiful theming across the CiviCRM ecosystem, while supporting the ongoing work of modernising the underlying markup.

If you prefer the video version…

Machine assistance disclaimer: this blog post is based on my video above; to save time an LLM provided help restructuring the video's transcript as a blog, which was then edited into this.

Comments

Great video and write-up. Many thanks @nicol & @artfulrobot for all the thought and effort leading this initiative from initial ideas to live implementation.