XF 2.3 A first look at XenForo 2.3

Well, here we are with our first Have you seen thread for XenForo 2.3.

It's been a long time coming, and for various reasons that we will go into later, it has changed quite a bit from what we had originally intended it to be, but it's finally ready to start showing you what's new.

tl;dr: there's a video at the end of this post.

Dark mode​

A lot of the new stuff in XenForo 2.3 is related to performance improvements that won't be immediately apparent on first glance, but there is one new feature in particular that is very obvious, and that is the new dark mode.







If the device with which you are browsing a XenForo site is configured to use its own dark mode, XenForo will switch itself to use the dark theme. Alternatively, you can request either the light, dark, or system-controlled theme using the gadget in the footer next to the style chooser. This will switch the mode instantly, without a page reload.


This is not XenForo 3.0​

This is not the big design overhaul that was originally targeted for 2.3, which included sweeping changes to the template system and introduced a range of new technologies to provide a significant improvement to many areas of XenForo.

When it became clear that the new design would introduce unresolvable backward-compatibility issues, the decision was made to back out the new design and reserve it for a version of XenForo we will call 3.0. Instead, we decided to ship the new functionality that we have built for 2.3 without the new design, so that existing users can gain access to all the new features without worrying about a major maintenance job to get it integrated.

Some of the new systems that we built to support the 3.0 design have been adapted to work with the 2.3 system, and support for dark mode is one of them.

Style variations​

The dark mode is built on top of a brand new style variations system. This system allows defining alternate sets of certain style properties, namely colors, to be switched dynamically without a page reload.

We currently expose two variations, which we dub 'default' and 'alternate'. In the default style, the default variation corresponds to the light theme and the alternate variation corresponds to the dark theme.

When both variations correspond to different style types (that is, light or dark), we expose them using the prefers-color-scheme media query. This automatically selects a variation based on the device's preferred color scheme when a user has not explicitly chosen a variation to use.

However, you could also set both variations as light or dark. In this case, the gadget in the footer will display the variation names instead, still allowing users to switch to a different color palette at whim.

Many sites running XenForo already run with a third-party dark style, but it's important to note that offering both light and dark styles to your visitors would previously have entailed providing completely separate styles, and while the dark style may have inherited most of its templates and style properties from a light parent, there would still have been a performance penalty tied to supporting both of these styles. With the style variations system in XenForo 2.3, this is no longer the case. Both variations of the style are handled within a single style. Those administrators who maintain multiple styles and have to handle inheritance between them will appreciate how much easier this will make style management.


Default and alternate​

Furthermore, while light styles can now be extended to support a dark variation, the same is true of existing dark styles, which can now define a light variation. At present, we refer to the Default and Alternate variations, where Default could be light or dark, and Alternate is (usually) the opposite.


Style properties​

From a style designer's perspective, style variations are handled as part of the style properties system. Style properties defined as a color value may be edited to enable variations, in which case they will accept values for each of the variations defined in the style.


With variations enabled, the user is free to define completely different versions of the color for each variation.


Note that the ability to support variations is limited to color value type style properties and does not extend to CSS-type properties. Of course, that does not mean that CSS-type properties are unable to benefit from the variations system, because the color values they reference may themselves be variants. That is to say, if your header CSS uses @xf-chromeBg, which in turn references @xf-paletteColor5, then it will automatically pick up the variant value of @xf-paletteColor5 when defined.

Future extension​

In a future version of XenForo, depending upon feedback, we may add support for defining additional variations, and extend the range of style properties which support variations beyond color properties. This could allow variations with different padding or typography choices, all within a single style.

UI improvements​

You will notice that we have significantly increased the size of the color preview chip next to these controls, and that the style property editor has become faster to operate, as style property changes are now saved without the need to reload the page.

Additionally, in style properties where palette colors are referenced, variations are automatically inherited when using either the default or alternate fields, and can be manipulated using the standard color editing functions provided by XenForo, such as darken and xf-intensify.

Naturally, the xf-intensify and xf-diminish functions now respect the light or dark mode within which they are operating, pushing colors either darker or lighter depending upon the way in which the current variation is flagged.

HSL color space​

You may have spotted from the images shown so far that we are now making use of HSL color space. While colors in XenForo were largely defined in RGB format, either as RGB decimal or hexadecimal values, this system presents challenges to some users, as adjustment of red, green and blue values is required to achieve even simple changes like making a color darker. HSL (hue, saturation and lightness) brings a more human-friendly color system, where the tone (hue) of the color is defined with a single value, then the intensity (saturation) and brightness (lightness) can also be adjusted with a single value change.

The color picker has been updated to reflect this change.


CSS variables​

Furthermore, each component of the HSL colour is now represented as a CSS variable. In XenForo 2.3 this allows the switching between light and dark variations, but its full utility will become apparent with XenForo 3.

A fun thing to try when you get access to 2.3, use your browser's inspector to locate the HSL values for paletteNeutral3, defined as the CSS variables --xf-paletteNeutral3--h, --xf-paletteNeutral3--s, and --xf-paletteNeutral3--l and use your cursor keys to adjust the value up and down. You will see that all instances of that color in use on the page react immediately, regardless of any adjustments made to them in subsequently inherited colors. Here, we have adjusted xf-paletteNeutral3 from hsl(0, 0%, 8%) to hsl(200, 50%, 20%) using the inspector in Chrome, resulting in changes to various backgrounds and borders that are based on adjustments of the original color.


Of note here is that the operations being performed on the colors are done on the client side rather than with the server-side LESS processor, so it's much easier to prototype sweeping color adjustments.

Making it your own​

In order to prevent any unexpected behavior when you upgrade to XenForo 2.3, we will not make changes to any of your styles. This includes marking your styles as supporting variations.

To enable variations, edit each of your styles in turn and toggle the 'Enable variations' option. Next, jump into the style properties editor for that style and concentrate on the Color palette and Basic colors groups.

In the default style, we took each of the Palette and Accent colors and reduced their saturation and lightness a little for the dark variation so that they are a little more muted against a dark background. We did not adjust the Neutral colors at all.

Next, in the Basic colors group, we switched around references to the Neutral 3 (dark) and Neutral 1 (light) colors, and in some cases reversed the references to palette colors, so references to Palette 1 now point to Palette 5 etc., making further adjustments with the built-in color functions as necessary.


If you follow these guidelines with your own styles, you should be able to quickly build dark variations that are suitable for use on your site.


Here's a video showing everything in action:

To view this content we will need your consent to set third party cookies.
For more detailed information, see our cookies page.
For happy to see this update!

Seeing that dark mode is more supported bodes well as many users on my site prefer it for accessibility reasons.

Is this a sign that accessibility is going to be more of priority in these coming releases? Forum users skew older and aging populations have issues with things like photosensitivity, migraines, reading difficulties with font sizes and whatnot. So this gives me hope, but I dont want my hopes to get too high.
You might be surprised at the current Lighthouse accessibility rating of the new dark style in 2.3.

I'll give you a clue, it's somewhere between 97 and 99 for the forum list, 96 and 98 for the forum view, and 98 and 100 for the thread view ;)
You might be surprised at the current Lighthouse accessibility rating of the new dark style in 2.3.

I'll give you a clue, it's somewhere between 97 and 99 for the forum list, 96 and 98 for the forum view, and 98 and 100 for the thread view ;)

What's the score on the same pages, on the same site, pre-2.3? Some folks have 96+ ratings now don't they?
Another potential issue may be the logo, which may need color adjustment due to the background change. If it is an SVG, there is a way to change its color with CSS. All in all, I’m looking forward to the rollout of this feature.
I think this is crucial @Kier @Chris D

We have quite a few sites / styles where the logo just wouldn't work with light and dark theme.

Using SVG also might not be an option for those logos (as we don't have a SVG and rebuilding the logo as a vector image might not be possible / make sense).

So without being able to alternate on the the logo we could probably only
  1. Not use the functionality at all
  2. Create an entirely new logo that works in light and dark themes
  3. Implement alternate for logo on our own
While 3) would most certainly be possible, I'd really appreciate if this was possible out of the box - not only for us but most likely for many customers that might want to take advantage of light / dark alternate but don't a have a logo that works for both.

How is user preference handled?
A user might want to use automatic (eg. system) preference on one device (like Smartphone) but a fixed choice of Light on another device (eg. desktop).
Would this be possible?
Last edited:
You can check yourself using the Lighthouse tab in the browser tools.

I must not be with you. Maybe I'm confused. I was curious how the ratings you posted for 2.3 compared to 2.2. How could I compare those on a different site from where you for the 2.3 ratings?
The installation being tested for 2.3 is the same as this site as far as the style is concerned - a vanilla XF style.

That will provide a comparison as far as accessibility is concerned.
You can check yourself using the Lighthouse tab in the browser tools.
This is what I see for this page, this thread.


On-Topic: I do try my very best to keep my sight as accessible as possible, although it is not possible to be perfect. And the RAMP accessibility testing site limits you to just a few pages on the free plan for its monitoring.
Top Bottom