Is it possible to expose Vanilla Extract vars as part of component library?

[thedanchez]

Hello, I have a question -- I'm building a component library using vanilla-extract and had a question about something I would like to expose to my end-user (which are other developers).

I basically want to expose an "escape-hatch" hook along the lines of useTheme() which would allow developers using my component library to do the following if they need it.

// tokens would contain all the vanilla-extract defined vars that I used internally
const { tokens } = useTheme().

Is this possible to do? I know vanilla-extract compiles everything away at build-time but wanted to see if there was a way to do the above? Thanks for the help!

[askoufis]

This is definitely possible. Any vars (tokens) you create, whether that be with createVar, createThemeContract, or other APIs, are just strings. They can safely be exported from a .css.ts file and used within other styles (.css.ts files) or even at runtime in your components, just like how styles created with the style function are compiled away, but can still be referenced via their classname string (this is what ends up being exported in your .css.ts file).

As a small suggestion, I'd advise against exposing your tokens via a hook, if possible. Unless there's a specific reason you need to use a hook, a simpler approach could just be to document an exported vars or tokens object in your package, e.g. import { tokens } from "my-components-library". Exposing this via a function is fine, but naming that function like a hook can imply a more complex implementation to developers as they may think that useTheme is accessing context, or storing some kind of state.

[thedanchez]

Thank you so much @askoufis for replying! This is super helpful insight!

So the one thing that comes to mind as to why I was thinking about putting the tokens into a hook is that, there are certain tokens that would by dynamic in changing their underlying value whenever the aspects of my custom theme changes (e.g. light vs dark mode and different density settings: narrow vs regular vs wide). Would that be handled automatically if I used sprinkles with specific selectors?

Btw, I'm very new to vanilla-extract and am just trying to get my bearings with everything 😄

[askoufis]

Regardless of whether the values of your tokens are changing, the references to them (assuming you're using your the vars from your theme in sprinkles definitions) will not.

Here is an example I made that creates a theme contract and a theme, and then re-uses the vars from your theme contract in a sprinkles definition.

import { createThemeContract, createTheme } from "@vanilla-extract/css";
import { createSprinkles, defineProperties } from "@vanilla-extract/sprinkles";

// Reference your vars in other `.css.ts` files or at runtime
export const themeVars = createThemeContract({
  colors: { primaryLight: null, primaryDark: null },
});

// Export theme classname for usage in your app
export const theme1 = createTheme(themeVars, {
  colors: { primaryLight: "red", primaryDark: "darkRed" },
});

// Make more themes if you want

const colorProperties = defineProperties({
  conditions: {
    lightMode: {},
    darkMode: { "@media": "(prefers-color-scheme: dark)" },
  },
  defaultCondition: "lightMode",
  properties: {
    backgroundColor: themeVars.colors,
  },
});

const sprinkles = createSprinkles(colorProperties);

// Color mode aware primary button style
export const primaryButtonStyle = sprinkles({
  backgroundColor: { lightMode: "primaryLight", darkMode: "primaryDark" },
});

[thedanchez]

Really appreciate the explanation and sample @askoufis! That definitely answers my thoughts.

One last question just came to mind as I saw your sample here -- it's tangential but wanted to ask, what does it looks like to deal with themes (like colorMode) that are manually set by the end-user? I would imagine that is handled via using a custom selector and not using the browser @media to drive the light vs dark theme setting yeah?

[askoufis]

Correct. Looking at the vanilla extract docs site, we use a custom dark classname that's added/removed at runtime.