Is there a preferred way to do component-level theming _without_ *.stylex.ts? (Answer: No -- not really) #849

zaydek · 2025-01-12T05:38:43Z

zaydek
Jan 12, 2025

Instead of using global theming, I've been thinking about having components defining their own abstract theme tokens. This way I don't need to worry about components being tightly coupled to application-level theming tokens, and there are default values for everything even if I don't set any.

This is what I came up with:

import * as stylex from "@stylexjs/stylex";
import * as React from "react";
import { Center } from "~/components/center";
import { Row } from "~/components/flexbox/flexbox";
import { LucideIcons } from "~/components/lucide-icons";
import { Sx } from "~/styles/sx";
import { Spacing, Theme } from "~/styles/theme.stylex";

const CHECKBOX_BORDER_RADIUS = "--checkbox-border-radius";
const CHECKBOX_COLOR = "--checkbox-color";
const CHECKBOX_SIZE = "--checkbox-size";

const CHECKBOX_ICON_SIZE = "--checkbox-icon-size";

const defaults = {
  [CHECKBOX_BORDER_RADIUS]: "37.5%",
  [CHECKBOX_COLOR]: Theme.Brand,
  [CHECKBOX_SIZE]: "48px",
  [CHECKBOX_ICON_SIZE]: `calc(var(${CHECKBOX_SIZE}) / 2)`,
};

const vars = {
  CHECKBOX_BORDER_RADIUS: `var(${CHECKBOX_BORDER_RADIUS}, ${defaults[CHECKBOX_BORDER_RADIUS]})`,
  CHECKBOX_COLOR: `var(${CHECKBOX_COLOR}, ${defaults[CHECKBOX_COLOR]})`,
  CHECKBOX_SIZE: `var(${CHECKBOX_SIZE}, ${defaults[CHECKBOX_SIZE]})`,
  CHECKBOX_ICON_SIZE: `var(${CHECKBOX_ICON_SIZE}, ${defaults[CHECKBOX_ICON_SIZE]})`,
};

const styles = stylex.create({
  intrinsic: {
    blockSize: vars.CHECKBOX_SIZE,
    inlineSize: vars.CHECKBOX_SIZE,
  },

  // This is the background layer
  background: {
    ":focus-within::before": {
      borderRadius: "inherit",
      boxShadow: `0 0 0 2px ${vars.CHECKBOX_COLOR}`,
      content: "",
      inset: -2,
      pointerEvents: "none", // Ensure that this layer doesn't receive pointer events
      position: "absolute",
    },
    alignItems: "center",
    blockSize: vars.CHECKBOX_SIZE,
    borderRadius: vars.CHECKBOX_BORDER_RADIUS,
    display: "flex",
    inlineSize: vars.CHECKBOX_SIZE,
    justifyContent: "center",
    position: "relative", // For icon
  },
  unchecked: {
    backgroundColor: null,
    boxShadow: `inset 0 0 0 1px color-mix(in hsl, transparent, white 50%)`,
  },
  checked: {
    backgroundColor: vars.CHECKBOX_COLOR,
    boxShadow: `inset 0 0 0 1px color-mix(in hsl, transparent, white 50%)`,
    //// boxShadow: null,
  },

  // This is the foreground layer
  foreground: {
    blockSize: vars.CHECKBOX_ICON_SIZE,
    color: "white",
    inlineSize: vars.CHECKBOX_ICON_SIZE,
    inset: 0,
    margin: "auto", // Self-center
    pointerEvents: "none", // Ensure that this layer doesn't receive pointer events
    position: "absolute",
  },
});

export type CheckboxProps = Sx.IntrinsicComponentProps<"input"> & {
  // Require the checked state and the onChange event handler
  intrinsicProps: {
    checked: boolean;
    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
  };
};

function Checkbox(props: CheckboxProps): React.JSX.Element {
  return (
    <div
      {...stylex.props(
        styles.background,
        (() => {
          if (props.intrinsicProps.checked) {
            return styles.checked;
          } else {
            return styles.unchecked;
          }
        })(),
        props.stylex,
      )}
    >
      {/* This is the native input */}
      <input {...props.intrinsicProps} {...stylex.props(styles.intrinsic)} type="checkbox" />
      {props.intrinsicProps.checked && <LucideIcons.Check {...stylex.props(styles.foreground)} strokeWidth={4} />}
    </div>
  );
}

const custom = stylex.create({
  red: {
    [CHECKBOX_COLOR]: Theme.Red,
  },
  big: {
    [CHECKBOX_ICON_SIZE]: `calc(var(${CHECKBOX_SIZE}) / 2)`,
    [CHECKBOX_SIZE]: "64px",
  },
});

type UseCheckbox = {
  checked: boolean;
  setChecked: React.Dispatch<React.SetStateAction<boolean>>;
};

function useCheckbox(initialState: boolean): UseCheckbox {
  const [checked, setChecked] = React.useState(initialState);
  return { checked, setChecked };
}

export function UsageCheckbox(): React.JSX.Element {
  //// const checkboxes = [useCheckbox(false), useCheckbox(false), useCheckbox(false)];
  const checkbox1 = useCheckbox(false);
  const checkbox2 = useCheckbox(false);
  const checkbox3 = useCheckbox(false);

  return (
    <Center withMinBlockSize>
      <Row alignItems="center" gap={Spacing.Md}>
        <Checkbox
          //// stylex={custom.checkbox as stylex.StyleXStyles}
          intrinsicProps={{
            checked: checkbox1.checked,
            onChange: (e) => checkbox1.setChecked(e.target.checked),
          }}
        />
        <Checkbox
          stylex={custom.big as stylex.StyleXStyles}
          intrinsicProps={{
            checked: checkbox2.checked,
            onChange: (e) => checkbox2.setChecked(e.target.checked),
          }}
        />
        <Checkbox
          stylex={custom.red as stylex.StyleXStyles}
          intrinsicProps={{
            checked: checkbox3.checked,
            onChange: (e) => checkbox3.setChecked(e.target.checked),
          }}
        />
      </Row>
    </Center>
  );
}

So if you impose the constraint of not wanting to create a +1 file per component for coordinating themes, is there some other way to do this or is this reasonable? What I like about this is that I can still export the theme tokens and theoretically override them from another file.

Here's how this looks in practice:

icon.mp4

Answered by nmn

Jan 12, 2025

TLDR; This is what I was going to suggest as the canonical way to do this pattern.

In the future, we might let you use stylex.defineVars in any file so you wouldn't need to put the variables in a separate file, but there are very good reasons to not allow that for now. (co-location of variable defs would make compilation and caching a lot harder)

However, I would suggest against this pattern in general. This is a pattern we tried as well and it leads to a couple of problems:

It causes CSS bloat.

The benefit of atomic CSS is that common styles can be shared across your entire app. If every component defines its own variables this becomes impossible and you CSS will start to grow linearly …

View full answer

zaydek · 2025-01-12T05:43:25Z

zaydek
Jan 12, 2025
Author

Ah unfortunately it doesn't work if I separate custom into its own file because StyleX can't statically infer the CHECKBOX-* constants. I guess this is my sign to just use defineVars?

0 replies

zaydek · 2025-01-12T05:52:15Z

zaydek
Jan 12, 2025
Author

OK I think I see the light. This is likely the canoncial way to solve this problem, it simply requires creating a component.styelx.ts file but at that point it's very canonical and easy to reason about which I can appreciate.

// checkbox.stylex.ts
import * as stylex from "@stylexjs/stylex";
import { Theme } from "~/styles/theme.stylex";

export const CheckboxVars = stylex.defineVars({
  CheckboxBorderRadius: "37.5%",
  CheckboxColor: Theme.Brand,
  CheckboxSize: "48px",

  CheckboxIconSize: "50%",
});

// checkbox.tsx
import * as stylex from "@stylexjs/stylex";
import * as React from "react";
import { CheckboxVars } from "~/components/checkbox.stylex";
import { LucideIcons } from "~/components/lucide-icons";
import { Sx } from "~/styles/sx";

const styles = stylex.create({
  intrinsic: {
    blockSize: CheckboxVars.CheckboxSize,
    inlineSize: CheckboxVars.CheckboxSize,
  },

  // This is the background layer
  background: {
    ":focus-within::before": {
      borderRadius: "inherit",
      boxShadow: `0 0 0 2px ${CheckboxVars.CheckboxColor}`,
      content: "",
      inset: -2,
      pointerEvents: "none", // Ensure that this layer doesn't receive pointer events
      position: "absolute",
    },
    alignItems: "center",
    blockSize: CheckboxVars.CheckboxSize,
    borderRadius: CheckboxVars.CheckboxBorderRadius,
    display: "flex",
    inlineSize: CheckboxVars.CheckboxSize,
    justifyContent: "center",
    position: "relative", // For icon
  },
  unchecked: {
    backgroundColor: null,
    boxShadow: `inset 0 0 0 1px color-mix(in hsl, transparent, white 50%)`,
  },
  checked: {
    backgroundColor: CheckboxVars.CheckboxColor,
    boxShadow: `inset 0 0 0 1px color-mix(in hsl, transparent, white 50%)`,
    //// boxShadow: null,
  },

  // This is the foreground layer
  foreground: {
    blockSize: CheckboxVars.CheckboxIconSize,
    color: "white",
    inlineSize: CheckboxVars.CheckboxIconSize,
    inset: 0,
    margin: "auto", // Self-center
    pointerEvents: "none", // Ensure that this layer doesn't receive pointer events
    position: "absolute",
  },
});

export type CheckboxProps = Sx.IntrinsicComponentProps<"input"> & {
  // Require the checked state and the onChange event handler
  intrinsicProps: {
    checked: boolean;
    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
  };
};

export function Checkbox(props: CheckboxProps): React.JSX.Element {
  return (
    <div
      {...stylex.props(
        styles.background,
        (() => {
          if (props.intrinsicProps.checked) {
            return styles.checked;
          } else {
            return styles.unchecked;
          }
        })(),
        props.stylex,
      )}
    >
      {/* This is the native input */}
      <input {...props.intrinsicProps} {...stylex.props(styles.intrinsic)} type="checkbox" />
      {props.intrinsicProps.checked && <LucideIcons.Check {...stylex.props(styles.foreground)} strokeWidth={4} />}
    </div>
  );
}

// idea.tsx
import * as stylex from "@stylexjs/stylex";
import * as React from "react";
import { Center } from "~/components/center";
import { Checkbox } from "~/components/checkbox";
import { CheckboxVars } from "~/components/checkbox.stylex";
import { Row } from "~/components/flexbox/flexbox";
import { Spacing, Theme } from "~/styles/theme.stylex";

const red = stylex.createTheme(CheckboxVars, {
  CheckboxColor: Theme.Red,
});
const big = stylex.createTheme(CheckboxVars, {
  CheckboxSize: "64px",
});

type UseCheckbox = {
  checked: boolean;
  setChecked: React.Dispatch<React.SetStateAction<boolean>>;
};

function useCheckbox(initialState: boolean): UseCheckbox {
  const [checked, setChecked] = React.useState(initialState);
  return { checked, setChecked };
}

export function UsageCheckbox(): React.JSX.Element {
  //// const checkboxes = [useCheckbox(false), useCheckbox(false), useCheckbox(false)];
  const checkbox1 = useCheckbox(false);
  const checkbox2 = useCheckbox(false);
  const checkbox3 = useCheckbox(false);

  return (
    <Center withMinBlockSize>
      <Row alignItems="center" gap={Spacing.Md}>
        <Checkbox
          intrinsicProps={{
            checked: checkbox1.checked,
            onChange: (e) => checkbox1.setChecked(e.target.checked),
          }}
        />
        <Checkbox
          stylex={big}
          intrinsicProps={{
            checked: checkbox2.checked,
            onChange: (e) => checkbox2.setChecked(e.target.checked),
          }}
        />
        <Checkbox
          stylex={red}
          intrinsicProps={{
            checked: checkbox3.checked,
            onChange: (e) => checkbox3.setChecked(e.target.checked),
          }}
        />
      </Row>
    </Center>
  );
}

3 replies

nmn Jan 12, 2025
Collaborator

TLDR; This is what I was going to suggest as the canonical way to do this pattern.

In the future, we might let you use stylex.defineVars in any file so you wouldn't need to put the variables in a separate file, but there are very good reasons to not allow that for now. (co-location of variable defs would make compilation and caching a lot harder)

However, I would suggest against this pattern in general. This is a pattern we tried as well and it leads to a couple of problems:

It causes CSS bloat.

The benefit of atomic CSS is that common styles can be shared across your entire app. If every component defines its own variables this becomes impossible and you CSS will start to grow linearly with the number of components. This is a problem for larger apps which StyleX and Atomic CSS in general helps avoid.

Too many CSS vars cause perf issues

There is some magical unknown number where if you make too many CSS variables the styling engine of the browser will screech to a halt. This number is variable and depends on your exact machine but just know that each new variable you define has a compounding performance effect.

Defining your variable as inherits: false in a @property rule helps avoids these problems but that also makes your variable not inheritable. (All variables created for dynamic styles have this by default for this reason)

Again, the best way to solve this problem is to StyleXStyles props when that's possible. I know that your example is explicitly about using the variable in multiple styles which would be worse to customize. But for these usecase you can just accept a values as props and use dynamic styles instead.

// checkbox.tsx
import * as stylex from "@stylexjs/stylex";
import * as React from "react";
import { CheckboxVars } from "~/components/checkbox.stylex";
import { LucideIcons } from "~/components/lucide-icons";
import { Sx } from "~/styles/sx";

const styles = stylex.create({
  intrinsic: (size: number) => ({
    blockSize: size,
    inlineSize: size,
  }),

  // This is the background layer
  background: (size: number, color: string, radius: number) => ({
    ":focus-within::before": {
      borderRadius: "inherit",
      boxShadow: `0 0 0 2px ${color}`,
      content: "",
      inset: -2,
      pointerEvents: "none", // Ensure that this layer doesn't receive pointer events
      position: "absolute",
    },
    alignItems: "center",
    blockSize: size,
    borderRadius: radius,
    display: "flex",
    inlineSize: size,
    justifyContent: "center",
    position: "relative", // For icon
  }),
  unchecked: {
    backgroundColor: null,
    boxShadow: `inset 0 0 0 1px color-mix(in hsl, transparent, white 50%)`,
  },
  checked: (color: string) => ({
    backgroundColor: color,
    boxShadow: `inset 0 0 0 1px color-mix(in hsl, transparent, white 50%)`,
    //// boxShadow: null,
  }),

  // This is the foreground layer
  foreground: (size: number | string) => ({
    blockSize: size,
    color: "white",
    inlineSize: size,
    inset: 0,
    margin: "auto", // Self-center
    pointerEvents: "none", // Ensure that this layer doesn't receive pointer events
    position: "absolute",
  }),
});

export type CheckboxProps = Sx.IntrinsicComponentProps<"input"> & {
  // Require the checked state and the onChange event handler
  intrinsicProps: {
    checked: boolean;
    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
  };
  size?: number | string,
  color?: string,
  radius?: number | string,
};

export function Checkbox({size, color, radius, ...props}: CheckboxProps): React.JSX.Element {
  return (
    <div
      {...stylex.props(
        styles.background(size, color, radius),
        props.intrinsicProps.checked
          ? styles.checked(color)
          : styles.unchecked,
        props.stylex,
      )}
    >
      {/* This is the native input */}
      <input 
        {...props.intrinsicProps}
        {...stylex.props(styles.intrinsic(size))}
        type="checkbox"
      />
      {props.intrinsicProps.checked && <LucideIcons.Check
        {...stylex.props(styles.foreground(size))}
        strokeWidth={4}
      />}
    </div>
  );
}

This ends up creating the same number of variables as what you did but all of these variables are inherits: false and don't cause the performance issues. The styles are still sharable across components and the API is simpler.

Side Note

<div
  {...stylex.props(
    styles.background,
    (() => {
      if (props.intrinsicProps.checked) {
        return styles.checked;
      } else {
        return styles.unchecked;
      }
    })(),
    props.stylex,
  )}
>

This inline function is deopt for no reason.

If you used ternary expressions they are optimized by StyleX and the stylex.props call is
pre-computed at compile time.

<div
  {...stylex.props(
    styles.background,
    props.intrinsicProps.checked
      ? styles.checked
      : styles.unchecked,
    props.stylex,
  )}
>

Not a big deal as stylex.props is a very fast function anyway, but worth knowing.

Answer selected by zaydek

zaydek Jan 13, 2025
Author

Much appreciated @nmn. Yeah, the other nuance with defining vars for simple things like components is you have to remember to consume the vars as opposed to use stylex={...} and overwrite the properties you want to control. Part of that has to do with understanding inherit with respect to things like text and there are other tricks like currentColor so you can worry about the color property as opposed to borderColor or backgroundColor. The other thing I recently discovered is that currentColor works fine with things like color-mix so that's a bonus.

I will probably only use define vars for top-level application theming and simply using stylex overrides if I need to manipulate properties. Sometimes I want to be able to control the styling on nested elements but if you simply export a component (creating Foo.Root, Foo.Icon and so on, then you can use stylex no problem. If you use something more abstract like Foo which could have many nested elements, you basically have to use theming but you also end up authoring some arbitrary convention over how variables map to properties and it's not my favorite. So anyway, learning as I go but coming to many of the same conclusions as you've shared so thank you for helping me with my understanding.

I tend to use IIFEs to model ternaries because prettier makes it too hard for me to read conditional code (as one line). I also think IIFE looks a little more like https://lightningscript.dev/ which makes me happy. That being said, I try to use the variants pattern to move all the logic of the component. So in this case I did this which I think is a clever workaround.

const checked = stylex.create({
  false: {
    ...
  },
  true: {
    ...
  },
});

Here's how this component turned out if you're curious:

checkboxes2.mp4

Turns out I can't reliably use the psuedo element for the focus ring because using a negative inset actually misaligns the border-radius when you use % based values like 37.5%. It's almost imperceptible but it's there. So using box-shadow with a masking layer seems to do the trick without any fancy math.

nmn Jan 13, 2025
Collaborator

So in this case I did this which I think is a clever workaround.

Interesting!

I can't reliably use the psuedo element for the focus ring

Shadows for outlines always! Or in the near future, a fixed element placed with Anchor Positioning.

necolas · 2025-01-14T22:04:13Z

necolas
Jan 14, 2025
Collaborator

FWIW, it will be easier for us to understand topics of discussion in the future if you make example code simpler and limited to the topic at hand.

I've been thinking about having components defining their own abstract theme tokens. This way I don't need to worry about components being tightly coupled to application-level theming tokens, and there are default values for everything even if I don't set any.

Avoiding the coupling to app tokens is a requirement for many component libraries! This is something that you can do in StyleX by defining the variables in a separate file, as you did in your later code snippets. A top-level theme can then import all the CSS var fragments from components and set new values for them - the theme style can then be set on the app's root element and it will restyle all the components.

If every component defines its own variables this becomes impossible and you CSS will start to grow linearly with the number of components.

Whether defineVars is called in files "owned" by components or the app shouldn't make a difference - all those vars become "root" variables. The number of variables is the same, but in the former case there isn't a tight coupling caused by components having to know the names of vars defined by the app.

Again, the best way to solve this problem is to StyleXStyles props when that's possible.

This isn't a solution for re-theming though - it only restyles instances, and creates inline styles.

3 replies

zaydek Jan 15, 2025
Author

This might be easier to read as a fullscreen gist: https://gist.github.com/zaydek/8f3f5c491f0b5e8712e542c218d596b2

Thanks @necolas, I appreciate your reply. I have a somewhat strange use case which I originally didn't know if StyleX can support, so I tried a lot of things and finally landed on something I like.

This is kind of a long post, but I want to fully describe the problem that led me to the solution at hand, what it has to do with the APIs StyleX offers, and my process of narrowing down how to use defineVars in a way that "agrees" with me while still allowing arbitrary styling like seen in the video.

Overview

Here's a quick overview before I share some code to help illustrate the approach for others:

Essentially, I want to have my own "component studio" where I can easily introspect a component's theme and props. The reason for this is that I am trying to remove Figma from my process (it's not really AI-enabled yet), but I still need a way to reason about components separate from my apps.

definevars.mp4

I quickly bootstrapped this editor tool, which currently supports only a couple of types (e.g., StyleX themes defined by defineVars and some simple primitives like string, number, etc.). My hope is to expand it to support most prop types so I can "visualize" and emit themes as code (essentially copy-paste the result theme and props).

This is a simple component I can see myself repurposing in many places. A concern I've had for a long time with any CSS methodology is the risk of hardcoding values, which leads to rebuilding the same component or unpredictably concatenating strings or merging inline styles. I've had bad enough bad experiences doing this in the past that I really want to double down on a "correct" solution that works with StyleX.

The problem

My apprehension with the .stylex.ts pattern stems from a few concerns:

Needing to create and maintain n+1 file per component

Needing to access defaults values for theme properties

For example:

// foo.stylex.ts
const fooVars = stylex.defineVars({
  blockSize: 16,
});

// foo.tsx
console.log(fooVars.blockSize);
// ^ I want to be able to access 16 but instead I get the mangled CSS variable
// This is useful to me for implementing the component studio concept as shared above (video)

Needing to set theme properties to arbitrary values

Originally I was content with the createTheme API which works well if you know all of the theme values in advance (hard coding values). This is reasonable most of the time but what if you want to do something like I shared above or inject styles via a backend?. In that case, it occurs to me that createTheme doesn't work anymore (because it doesn't appear to support dynamic values).

Alternatively, I could always do something (perhaps naive) like this:
```
const styles = stylex.create({
  foo: (theme: FooTheme) => ({
    blockSize: theme.blockSize,
    ...
  }),
});
```
But it becomes redundant because you have to remember to expose the theme argument everywhere styling might be needed. So you sort of end up just making all styles accept a theme argument instead, and then needing to remember to invoke all styles as functions going forwards, e.g. styles.foo(theme) instead of styles.foo, which can easily leads to bugs.

So both using createTheme and inline styles/their equivalent seem to not be able to solve this problem or solve this problem poorly.
Themes should be self-documenting

Needing to look at a separate file seemed like it might cause more indirection. But without defineVars, I'm left with something like type FooProps = { theme: Partial<FooTheme> }, which I dislike because it overloads component props, adding more complexity per component.

It should be clear by now that ignoring stylex.defineVars was beginning to cause more issues than it solved.

Small aside @nmn: I noticed themes created by createTheme don't seem to support merging. For instance, if I have a blueTheme theme and a bigTheme theme, I remember not being able to do stylex={[blueTheme, bigTheme]}. I think the last theme wins or something similar, but it didn't work for me.

The solution

Here's the solution I came up with:

Define component-level vars using stylex.defineVars in a separate .stylex.ts file:

// avatar.stylex.ts

// Default values are exported so they may be consumed as client-side state for interactivity
export const avatarDefaultTheme = {
  SIZE: 48,
  CONTENT_SIZE: 0.5,
  BACKGROUND_COLOR: themeVars.colorAccent,
  BADGE_BOX_SHADOW_SPREAD: 4,
  BADGE_SIZE: 0.4375,
  BADGE_ICON_SIZE: 0.625,
} as const;
export type AvatarDefaultTheme = typeof avatarDefaultTheme;

// Serialized theme, for typical use with StyleX styles
export const AVATAR_THEME = stylex.defineVars<
  MapValuesToString<AvatarDefaultTheme>
>({
  SIZE: `${avatarDefaultTheme.SIZE}px`,
  CONTENT_SIZE: `round(${avatarDefaultTheme.CONTENT_SIZE * 100}%, 1px)`,
  BACKGROUND_COLOR: avatarDefaultTheme.BACKGROUND_COLOR,
  BADGE_BOX_SHADOW_SPREAD: `${avatarDefaultTheme.BADGE_BOX_SHADOW_SPREAD}px`,
  BADGE_SIZE: `round(${avatarDefaultTheme.BADGE_SIZE * 100}%, 1px)`,
  BADGE_ICON_SIZE: `round(${avatarDefaultTheme.BADGE_ICON_SIZE * 100}%, 1px)`,
});

Where MapValuesToString is defined as:

export type MapValuesToString<T> = { [K in keyof T]: string };

Then in a component file (not a .stylex.ts file):

// exmaple.tsx

// Define the custom theme, using the same syntax as AVATAR_THEME but with custom overrides.
// Note to self: AvatarDefaultTheme should probably be Partial<AvatarDefaultTheme> but then it gets kind of noisy using ?? 🤔
const styles = stylex.create({
  theme: (custom: AvatarDefaultTheme) => ({
    [AVATAR_THEME.SIZE]: `${custom.SIZE}px`,
    [AVATAR_THEME.CONTENT_SIZE]: `round(${custom.CONTENT_SIZE * 100}%, 1px)`,
    [AVATAR_THEME.BACKGROUND_COLOR]: custom.BACKGROUND_COLOR,
    [AVATAR_THEME.BADGE_BOX_SHADOW_SPREAD]: `${custom.BADGE_BOX_SHADOW_SPREAD}px`,
    [AVATAR_THEME.BADGE_SIZE]: `round(${custom.BADGE_SIZE * 100}%, 1px)`,
    [AVATAR_THEME.BADGE_ICON_SIZE]: `round(${custom.BADGE_ICON_SIZE * 100}%, 1px)`,
  }),
});

...

// My use case: define theme as a runtime value
const theme = useState(avatarDefaultTheme);

...

// Use the runtime theme as an override
<Avatar _stylex={styles.theme(theme)} ... />

Why I like this solution

The default theme is available as a plain JavaScript object with plain values

I need the default theme as a JavaScript value so the component studio can base its inputs on it. I think I could probably just query the CSS variables for their values but I worry about getting the wrong values if theming is already active.
Renaming symbols still works

Using stylex.defineVars<MapValuesToString<AvatarDefaultTheme>> creates a binding between the default theme keys and the StyleX theme. This allows me to rename symbols in one place and propagate changes everywhere.

With VS Code settings like "typescript.preferences.useAliasesForRenames": false, renaming a symbol deeply propagates the change instead of aliasing, making the process more seamless.

Example:
```
const foo = { a: "Hello, world!" };
const { a } = foo;
```
Renaming a to b changes it deeply, avoiding aliasing issues:
```
const foo = { b: "Hello, world!" };
const { b } = foo;
```
This pattern allows me to use defineVars effectively, accessing default values and customizing runtime logic without being limited to statically known themes.
Implicit self-documentation

Despite needing to create/maintain a separate file, the separate file is only concerned with documenting theming for any given component. This seems better than needing to overload component props or write (outdated) documentation.

Anyway this is a roundabout way of saying that I have found defineVars to be very helpful for my use case provided I export my own default values. If you have any further recommendations or advice I'd be very pleased to hear them. Will tag @nmn here as well. 🙂

I hope I provided enough code that it's reasonable to follow along. Happy to post the real thing in a gist if someone wants to scrutinize this approach more carefully. I don't think I'm doing anything "weird" here other than creating my own default values and consuming them, but I'm not sure if there's a more practical way for me to do this.

necolas Jan 15, 2025
Collaborator

I noticed themes created by createTheme don't seem to support merging. For instance, if I have a blueTheme theme and a bigTheme theme, I remember not being able to do stylex={[blueTheme, bigTheme]}

if that's true, it sounds like a bug

zaydek Jan 15, 2025
Author

OK thanks. I suspected it wasn't intentional behavior. I created an issue with the repro: #861.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Is there a preferred way to do component-level theming _without_ *.stylex.ts? (Answer: No -- not really) #849

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 3 comments 6 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

Is there a preferred way to do component-level theming _without_ *.stylex.ts? (Answer: No -- not really) #849

zaydek Jan 12, 2025

It causes CSS bloat.

Replies: 3 comments · 6 replies

zaydek Jan 12, 2025 Author

zaydek Jan 12, 2025 Author

nmn Jan 12, 2025 Collaborator

It causes CSS bloat.

Too many CSS vars cause perf issues

Side Note

zaydek Jan 13, 2025 Author

nmn Jan 13, 2025 Collaborator

necolas Jan 14, 2025 Collaborator

zaydek Jan 15, 2025 Author

Overview

The problem

The solution

Why I like this solution

necolas Jan 15, 2025 Collaborator

zaydek Jan 15, 2025 Author

zaydek
Jan 12, 2025

Replies: 3 comments 6 replies

zaydek
Jan 12, 2025
Author

zaydek
Jan 12, 2025
Author

nmn Jan 12, 2025
Collaborator

zaydek Jan 13, 2025
Author

nmn Jan 13, 2025
Collaborator

necolas
Jan 14, 2025
Collaborator

zaydek Jan 15, 2025
Author

necolas Jan 15, 2025
Collaborator

zaydek Jan 15, 2025
Author