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.
I used to think so too. I was very, very wrong. The majority of XenForo installations make minor colour and font adjustments and leave it at that, so actually the default theme is of paramount, critical importance.
🙋‍♂️ that is me, in 2.3 I don’t even think I’ll bother with colour adjustments.
Can we use the prefers-color-scheme media query in our extra.less to define other custom properties?
Without having seen any code yet myself:
You could do that, but that alone most certainly would not work if the user made an explicit theme choice, eg. overriding system / browser provided prefers-color-scheme
Last edited:
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 vactor 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 use but most likely for many customers aht 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?
We're actively looking into this.
Ok honestly how many times have people watched the video? Be honest everyone? ;) I've watched twice looking for clues lol. 🕵️‍♂️
I did, I even searched when the page source was displayed for a .webp ending on the images or something in the code that would give it away. I also figured it was something in the ACP portion but I only see webhooks.

Always Sunny Reaction GIF
You could do that, but that alone most certainly would not work if the user made an explicit theme choice, og. overriding system / browser provided prefers-color-scheme
Regardless of whether the style variant is selected automatically or manually, from a logical point of view, it is still a case of preferring a color scheme. Hence, it would be logical to expect the manual choice of style variants to respect prefers-color-scheme.
Hence, it would be logical to expect the manual choice of style variants to respect prefers-color-scheme.
Hmm .. no?

If system preference (eg. prefers-color-scheme) should always have precedence it would not make sense to offer the user choice to override this for XenForo.
(As the override would have no effect if prefers-color-scheme always has precedence)
Last edited:
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.
My (free) Svg Template add-on should work with this new style variant system. But it will likely need some work since the URL needs to be unique per variation :(

You basically put an SVG into the template system (an SVG is just XML aka text!), and then have the full power of XF's conditionals which means you can make it alter itself based on XF style properties. The style property integration then manages the actual URL for you.

There is also support to render the SVG as a PNG server side as some mobile devices have horrible SVG performance.
Last edited:
If system preference (eg. prefers-color-scheme) should always have precedence it would not make sense to offer the user choice to override this for XenForo.
Whichever switch one pulls (system or Xenforo), the action’s motive is still the same: control of the color scheme. So if XenForo knows that the user’s manual choice of style variant is based on color scheme preference, why ignore prefers-color-scheme? It’s a piece of meaningful code, why not act upon it and serve the user as a result? I’m thinking about it a bit along the lines of !important in CSS.
If my forum doesn't add the feature of making custom styles, I'll be pretty sad.
That feature looks so sick! Imagine: You can choose the colors without opening developer tools!
I am sorry, but I don't understand what you are trying to tell me :(

XenForo 2.3 will have this GUI for users to choose color scheme:

Usage Scenario
A user has set its device / browser to prefer a dark theme and visits a XenForo 2.3 website (that has a default style which supports dark / light color theme) as a guest for the very first time.

XenForo detects prefers-color-scheme dark and user color theme choice = System and displays the site with a dark theme.

After the page has completed loading, the user clicks on Light in the menu.

What should happen?
  1. XenForo should switch display to light, effectively ignoring prefers-color-scheme because the user explicitly chose to override browser / system preference.
    This is what I would expect and what I think XenForo developers have implemented (I might be wrong on that assumption though)
  2. The display should not switch to Light but still respect prefers-color-scheme, eg. stay in Dark.
    This is your suggestion (as far as I understood your comments)
If 1) is the desired behaviour, putting
@media  (prefers-color-scheme: light)
/* Some additional CSS / LESS to use for light color theme */
into extra.less wouldn't work as expected - those definitions would only be used if prefers-color-scheme is light.
They would not be used if it is dark but the user explicitly choose Light (instead of System)

If 2) is the desired behaviour:
Why should there even be an option to choose anything other than System (= prefers-color-scheme) if System always has precedence anyway?
This just doesn't make sense to me.
Last edited:
I am sorry, but I don't understand what you are trying to tell me […]
Thank you for the detailed reply, which I have bracketed out for terseness! Your explanation is clear to me, and I agree with your argument as far as the orthodox approach to prefers-color-scheme. My thinking belongs more to what you’re entertaining in the parentheses here:
This is what I would expect and what I think XenForo developers have implemented (I might be wrong on that assumption though)
because some things may still be in the making, and we can affect the process by sharing our user experiences as well as voicing some practical suggestions.

I experimented with reworking our light styles into dark ones a while ago to see what was needed. What I remember in our particular case is that changing colors wasn’t enough. I had to change the logo, remove some background images and box shadows. I would most likely need to do the same in 2.3. However, the mechanism of style variation in the style property system is said to allow me to define only color properties. So to adapt those other non-color properties, I’d have to use the style template system.

The neatest way to define the non-color properties for a particular style variant in the templates would probably be under prefers-color-scheme. Those definitions could then be used in different ways conditionally: if “System” is selected in the style chooser, apply condition 1; if “Light,” apply condition 2; if “Dark,” apply condition 3:
  • condition 1 = your explanation of how prefers-color-scheme should work;
  • condition 2 = if prefers-color-scheme specifies light, apply the CSS properties to the light style variant;
  • condition 3 = if prefers-color-scheme specifies dark, apply the CSS properties to the dark style variant.
“System,” “Dark,” and “Light” in the style chooser all refer to the same set of style variants. What differs is the mechanism of choosing one or the other. We have all the information (style properties + templates) to present the style variant of choise correctly. The rest is programming logic. That is how my reasoning unfolds.
Those definitions could then be used in different ways conditionally: [...]if “Light,” apply condition 2;
  • [...]
  • condition 2 = if prefers-color-scheme specifies light, apply the CSS properties to the light style variant;
  • [...]
Hmm, so in this case you only want to apply the definitions if the user has selected Light and the browser / system preference is Light as well but not if the user has selected Light and the browser / system preference is Dark?

That should be doable.
Top Bottom