Dynamic Theming with StyleX - just looking for confirmation 🙏

[BMCwebdev]

Heyo everyone,

We’re starting to introduce customization capabilities into our design system, with a small, focused goal: allowing users to choose their primary color.

Background

Currently, we have a library of tokens built with defineVars, where we use readable string keys as the names, as requested by our design team.

export const colorPrimitives = {
  "--s-color-neutral-0": "#ffffff",
  "--s-color-neutral-100": "#f8f8f9",
  // ...
};

We also define semantic tokens that point to core tokens to provide an abstraction layer:

export const colorSemantic = {
  "--s-color-primary": "--s-color-peri-500",
};

export const coreTokens = defineVars({
  ...colorPrimitives,
  ...colorSemantic,
...

The Challenge

We want to enable users to dynamically change the primary color at runtime (e.g., based on API data or user preference).

I’ve looked into using createTheme, but it seems to be intended for static values known at build time. Since our customization might come from an API or user settings, this approach doesn’t seem feasible.

One potential solution I’ve considered is directly updating the CSS variables at the html or body tag level. Since we use named variables rather than hashed ones, this might be manageable. However, it feels a bit off given StyleX’s default behavior of hashing variable names, and I wonder if there’s a more “StyleX-native” way to handle this.

Also, I’d like to avoid using inline style attributes.

Question

Has anyone tackled dynamic theme customization with StyleX, especially where the colors are not known until runtime? Are there best practices or recommended approaches for this kind of use case?

Any guidance or examples would be greatly appreciated!

Thanks!

[BMCwebdev]

The only solution I can think of, if you’re using the default StyleX hashed variable names, is that you would point your hashed variable to a named variable (—s-color-primary) and then use JS to fetch the custom color value and redefine that named variable further down the tree.

[BMCwebdev]

Just hoping someone could confirm I am not missing something more fundamental about how theming works with StyleX. Thank you!

[zaydek]

I don't remember 100% how I solved this previously but it's something like the following if I remember correctly:

// Define Theme type
type Theme = {
  Foo: string,
  ...
}

// Define theme implentation
const styles = stylex.create({
  theme: (theme: Theme) => ({
    backgroundColor: theme.Foo,
    color: ...,
  }),
});

function Component(props: ComponentProps) {
  // Initialize theme
  const [runtimeObject, setRuntimeObject] = useState(...)
  
  // Mutate theme
  useEffect(() => {
    ...
  }, [...])

  return (
    <div {...stylex.props(styles.theme(runtimeObject))}>
      ...
    </div>
  );
}

I also went super with createTheme and basically worked out that you should use them statically but you could still write a meta application to help generate the values.

Video 1: https://www.youtube.com/watch?v=GXIWZOV_QvQ
Video 2: https://www.youtube.com/watch?v=TJkfFWwhPUs

That being said, if memory serves, use something like the create thing above I think that's all you need.

[zaydek]

@BMCwebdev

[BMCwebdev]

@zaydek just wanted to say thanks, I've had fires to put out this week, but I will be diving into this tomorrow and I really appreciate the feedback and help!

[nmn]

Please don't do this:

export const colorSemantic = {
  "--s-color-primary": "--s-color-peri-500",
};

Pointing one variable to another variable is inefficient and doesn't work the way people expect in CSS. --s-color-peri-500 is usually a constant in such example, so define constants in the file instead.

---

Re: Dynamic theming

The simplest way to do this with StyleX is to use the variables as keys within stylex.create.

const styles = stylex.create({
  dynamicTheme: (theme: Theme) => ({
    [coreTokens["--s-color-primary"]]: theme.colorPrimary,
    ...
  }),
});

StyleX variables can be used as both keys and values within stylex.create calls (and also stylex.keyframes if given types)

[nmn]

The .stylex.ts file is fine. You can define arbitrary local constants when using stylex.defineVars.

However, this looks pretty wrong and I don't know what you might be trying to do with:

export const scopeCssVars = stylex.createTheme($, {
  "--s-color-background-primary": $["--s-color-primary"],
  "--s-color-border-focused": $["--s-color-primary"],
  "--s-color-border-selected": $["--s-color-primary"],

  // "--s-button-primary-color-background": $["--s-color-background-primary"],
});

You're setting variables within a theme to point to other variables in the same theme?
This will create a cycle in CSS and won't work because every theme also sets all variable you don't override to their default value.

What are you trying to do here?

[BMCwebdev]

@nmn Thanks for the response, know you are a busy man. To clarify, I hope I am not creating circular references but rather re-establish the token relationships at a different DOM level.

My approach with scopeCssVars is an attempt to manually re-establish those token relationships at the child level after a parent element changes a base token. Without this second layer, changing --s-color-primary wouldn't propagate to variables like --s-color-background-primary or --s-button-primary-color-background that depend on it.

It's working in our testing, but I'm concerned it might not be the right pattern for scaling as our design system grows. Do you have any recommendations on implementing themes with layered tokens? Is this parent/child pattern with re-scoping variables considered a valid approach, or is there a more idiomatic way to handle this scenario with StyleX?

Thanks again!

[BMCwebdev]

Bringing back in that commented out one as well to show how there are more than 1 or 2 tiers of tokens deriving.

export const scopeCssVars = stylex.createTheme($, {
  "--s-color-background-primary": $["--s-color-primary"],
  "--s-color-border-focused": $["--s-color-primary"],
  "--s-color-border-selected": $["--s-color-primary"],
  "--s-button-primary-color-background": $["--s-color-background-primary"],
});

[BMCwebdev]

One other follow up, I was attempting to follow this idea you suggested to someone else: #566 (comment)

[BMCwebdev]

Actually this is not working for me. It only worked when running npm run dev or npm run storybook. I assume because of styles being injected (even though runtimeinjection is set to false?) rather than statically build.

In a static build, the tokes still resolve back to root

[BMCwebdev]

Going with the dynamic approach with inline style attribute for now. Originally thought I could avoid it, but its fine for now (company Content Security Policy really want to get rid of style attributes, but they are so ubiquitous)

I'm still curious about the work that has been mentioned in some other discussions about Reactive Variables in the future.

If useful for anyone else I will share some of my code. I am curious if you could add something like this to the recipes in the StyleX documentation. The ability to do this wasn't something I would have known by looking there.

Thanks for all the help @nmn

import * as React from 'react';
import * as stylex from '@stylexjs/stylex';
import { coreTokens } from '@acme/stitch-tokens/coreTokens.stylex';

// Define theme type (for documentation purposes in JSX file)
/**
 * @typedef {Object} StitchTheme
 * @property {string} primary - Primary brand color
 * @property {string} [secondary] - Secondary brand color (optional)
 * @property {string} [buttonPrimary] - Override for primary buttons (optional)
 */

// Dynamic theme styles following the maintainer's pattern
export const dynamicThemeStyles = stylex.create({
  apply: (theme) => ({
    // Base tokens
    [coreTokens["--s-color-primary"]]: theme.primary,
    [coreTokens["--s-color-secondary"]]: theme.secondary || '#381360',
    
    // Background colors
    [coreTokens["--s-color-background-primary"]]: theme.primary,
    [coreTokens["--s-color-background-primary-hovered"]]: `color-mix(in srgb, ${theme.primary}, black 10%)`,
    [coreTokens["--s-color-background-primary-pressed"]]: `color-mix(in srgb, ${theme.primary}, black 30%)`,
    
    // Border colors
    [coreTokens["--s-color-border-focused"]]: theme.primary,
    [coreTokens["--s-color-border-selected"]]: theme.primary,
    
    // Button colors
    [coreTokens["--s-button-primary-color-background"]]: theme.buttonPrimary || theme.primary,
    [coreTokens["--s-button-primary-color-background-hovered"]]: `color-mix(in srgb, ${theme.buttonPrimary || theme.primary}, black 10%)`,
    [coreTokens["--s-button-primary-color-background-pressed"]]: `color-mix(in srgb, ${theme.buttonPrimary || theme.primary}, black 30%)`,
  }),
});

// ThemeProvider Component
export function ThemeProvider(props) {
  const { children, theme = { primary: '#5165fe' } } = props;
  
  return (
    <div {...stylex.props(dynamicThemeStyles.apply(theme))}>
      {children}
    </div>
  );
}

// Basic theming example
import { dynamicThemeStyles } from '@acme/stitch-extension';
import * as stylex from '@stylexjs/stylex';

function App() {
  // Define a theme with a custom primary color
  const theme = {
    primary: '#00a550', // Green color
  };
  
  return (
    <div {...stylex.props(dynamicThemeStyles.apply(theme))}>
      <Button variant="primary">Primary Button</Button>
      <Checkbox isSelected>Checkbox example</Checkbox>
      <TextField label="Text Field Example" />
    </div>
  );
}