confused about createThemeContract

[dagda1]

@Vanilla-Extract looks really awesome so major props for this.

I am confused about createThemeContract or how I can achieve the goal of creating a component library as a 3rd party npm package that others can then change the styling at the component level. If we take the example of an input, I might have a input.css.ts file like this:

export const inputVars = createThemeContract({
  borderColor: null,
  borderColorFocus: null,
  borderColorInvalid: null,
  borderFocusColorinvalid: null,
  borderWidth: null,
  bgFocus: null,
  bgInvalid: null,
});

export const [themeClass, themeVars] = createTheme({
  borderColor: palette.trueGray900,
  borderColorFocus: palette.blue700,
  borderColorInvalid: palette.redError,
  borderFocusColorinvalid: palette.blue700,
  borderWidth: '2px',
  bfFocus: palette.blue100,
  bgInvalid: palette.redError,
});

export const input = style({
  ...vars.formControl,
  border: `${themeVars.borderWidth} solid ${themeVars.borderColor}`,
  selectors: {
    ':focus': {
      background: themeVars.bfFocus,
    },
    '.invalid': {
      background: themeVars.bgInvalid,
      borderColor: themeVars.borderColorInvalid,
    },
    '.invalid &:focus': {
      borderColor: themeVars.borderColorFocus,
    },
  },
});

I don't know how I can use the inputVars returned from createTheme because if I supply 2 arguments to createTheme then it returns a string, according to the type definition

export declare function createTheme<ThemeContract extends Contract>(themeContract: ThemeContract, tokens: MapLeafNodes<ThemeContract, string>, debugId?: string): string;

Also how can consumers of the package then change the theme to their needs?

[mattcompiles]

Hey Bud 👋

createTheme is both creating the CSS vars and creating CSS for this theme. createThemeContract only creates the CSS vars without any default values. This is mostly useful for bundle splitting themes or when you want a centralised contract that has no default values.

The following should work.

export const [themeClass, themeVars] = createTheme({
  borderColor: palette.trueGray900,
  borderColorFocus: palette.blue700,
  borderColorInvalid: palette.redError,
  borderFocusColorInvalid: palette.blue700,
  borderWidth: '2px',
  bfFocus: palette.blue100,
  bgInvalid: palette.redError,
});

export const input = style({
  border: `${themeVars.borderWidth} solid ${themeVars.borderColor}`,
  selectors: {
    ':focus': {
      background: themeVars.bfFocus,
    },
    '.invalid': {
      background: themeVars.bgInvalid,
      borderColor: themeVars.borderColorInvalid,
    },
    '.invalid &:focus': {
      borderColor: themeVars.borderColorFocus,
    },
  },
});

Then to create a different version of the theme you can do the following.

export const altThemeClass = createTheme(themeVars, {
  borderColor: palette2.trueGray900,
  borderColorFocus: palette2.blue700,
  borderColorInvalid: palette2.redError,
  borderFocusColorInvalid: palette2.blue700,
  borderWidth: '5px',
  bfFocus: palette2.blue100,
  bgInvalid: palette2.redError,
});

Passing existing vars to createTheme will create a theme that matches the contract of an existing one. Allowing users to create their own themes should just require you exporting the vars from your package.

[dagda1]

@mattcompiles thank you for the answer. It just clicked that I need to add the theme class to a container element. I think I missed that in the docs.

Do you have any recommendations for supplying a default theme that users of the package can override only if needed?

One way of doing this is to accept the theme as a prop which is only a string so sort of lacks good type safety

So I could have a wrapper component like this:

import type { FC } from "react";
import { Input, InputProps } from "./Input";
import { themeClass } from "./Input.css";

type InputWrapperProps = InputProps & {
  theme?: typeof themeClass; // this is string, is there a better way?
};

export const InputWrapper: FC<InputWrapperProps> = ({
  theme = themeClass,
  ...props
}) => (
  <div className={theme}>
    <Input {...props} />
  </div>
);

And then users can either use the default or supply their own:

I've created an example codesandbox with an example of the above.

I'm excited about this project and I think I might finally be able to put the SASS away!

[mattcompiles]

I hear you about the type safety, but I think the bigger concern with type safety is ensuring the custom theme has been initialised correctly which vanilla-extract solves for you. Don't think applying the theme via className is a huge issue as it keeps it clear that all theming is done via CSS, not via some magic mechanism.

Also, if you'd prefer to have a default theme with no className then attaching it to the :root selector works nicely.

export const themeVars = createGlobalTheme(':root', {
  borderColor: palette.trueGray900,
  borderColorFocus: palette.blue700,
  borderColorInvalid: palette.redError,
  borderFocusColorInvalid: palette.blue700,
  borderWidth: '2px',
  bfFocus: palette.blue100,
  bgInvalid: palette.redError,
});