Proposal to add responsive variants to Recipes

[trekinbami]

Hi! ✋🏼

For utility components like Stack, Grid and other UI components like Button and Modal we have variants that need to be set per breakpoint. For a large scale project at work I've forked the repo and created something that works perfect. Wanted to share my idea and check out the API and see if it's something worth merging. I've seen this mentioned in other discussions (#1125, #1363, #497), but wanted to do my own proposal in its own thread.

For clarity. The goal is to have usage in React like the following:

<Stack direction={{ initial: "column", xl: "row" }} gap={{ initial: 1, xl: 2 }} />

As you can see, heavily inspired by Stitches.

Simplified working example on type level

I have created a simplified example of the API that works on type level: https://tsplay.dev/WvoPkw

API

In order to create the above, we need to be able add breakpoints. I wanted to stay as close as possible to Sprinkles, so we've called these conditions. Also; you don't want to specify breakpoints for every recipe that you create. So we have a factory function that takes in a set of conditions and returns a recipe function, just like the regular recipe API. It also needs an initialCondition for the use case where we use a responsive variant in a static manner (<Stack direction="row" />). Although, it's more of a fallbackCondition, I guess.

import { createRecipeFactory } from '@vanilla-extract/recipes';

const conditions = {
  initial: {},
  sm: { '@media': 'screen and (min-width: 768px)' },
  xl: { '@media': 'screen and (min-width: 1920px)' },
};

const recipe = createRecipeFactory({ conditions, initialCondition: "initial" })

If you don't want to use responsive variants, you can skip this step and just import recipe from the @vanilla-extract/recipes package.

Responsive variants

In order to keep the current API intact, I've introduced a responsiveVariants key. Only the variants defined here will be compiled to every breakpoint in the conditions passed to createRecipeFactory, similar to Sprinkles.

const stack = recipe({
  variants: {
    size: {
      large: {},
      small: {},
    },
  },
  responsiveVariants: {
    direction: {
      row: {},
      column: {},
    },
    gap: {
      0: {},
      1: {},
      2: {},
    },
  },
});

This could be used as follows:

const classNames = stack({ 
  direction: { initial: "column", xl: "row" },  
  gap: { initial: 0, sm: 2 },
  size: "large"
});

Default variants

These are now type checked through variants and responsiveVariants and applied accordingly.

Compound variants

These are correctly type checked through variants and responsiveVariants as well. But more importantly, when a responsiveVariant, that is part of a compoundVariant, is set to a certain variant on a certain breakpoint, the compoundVariant should kick in as well.

const iconButton = recipe({
  responsiveVariants: {
    size: {
      small: {},
      large: {},
    },
    padding: {
      compact: {},
      spacious: {},
    },
  },
  compoundVariants: [
    {
      variants: {
        size: 'small',
        padding: 'compact',
      },
      style: { // some styles },
      },
    },
    {
      variants: {
        size: 'small',
        padding: 'spacious',
      },
      style: { // some styles },
    },
  ],
});

This is a simplified (and dumb) example. But when we have the following runtime execution:

iconButton({ 
  size: { initial: "large", sm: "small", xl: "large" },  
  padding: { initial: "spacious" } 
});

The compound variant small + spacious should only kick in starting from the sm condition.

Overriding default conditions

This is not something that I've needed (yet?). For more granular control we could add a conditions property to a recipe that would merge (or override -- would be my personal preference) the passed default conditions inside of createRecipeFactory. You can see a simplified working version in the Playground posted above.

const stack = recipe({
  conditions: {
    mega: { '@media': 'screen and (min-width: 4096px)' },
  },
  variants: {
    size: {
      large: {},
      small: {},
    },
  },
  responsiveVariants: {
    direction: {
      row: {},
      column: {},
    },
  },
});

Of course, a potential simple alternative to this would be to just create a second recipe function with the createRecipeFactory so we don't need the conditions property inside of a specific recipe at all:

import { createRecipeFactory } from '@vanilla-extract/recipes';
import { conditions } from '@theme';

const newConditions = {
  ...conditions,
  mega: { '@media': 'screen and (min-width: 4096px)' },
};

const recipe = createRecipeFactory({ conditions, initialCondition: "initial" })

const stack = recipe({
  variants: {
    size: {
      large: {},
      small: {},
    },
  },
  responsiveVariants: {
    direction: {
      row: {},
      column: {},
    },
  },
});

Closing notes

This worked very well for us in our projects. Open to any suggestions! I've tried to minimize the impact on the existing API as much as I could. But I'm aware this will obviously have some impact on the codebase and would need to be maintained as well, etc.

Again, check out the playground to see how everything works on an API and type level: https://tsplay.dev/WvoPkw

[kasper573]

I needed something similar to this when i wanted recipes to automatically compile into sprinkles, so I made this: https://www.npmjs.com/package/vanilla-extract-recipe-factory. Now, it’s a bit different from your use case but we both felt that the regular recipe function isn’t enough for what we need, so we built a new one.

We’re likely not alone in this, so what’s the proper course of action for vanilla extract? I honestly think it’s fine the way it is. I think it’s really hard to provide a super flexible recipe function that satisfies everyones needs. Instead what vanilla extract does really well is to expose highly composable primitives, which the community can then use to build more specific and opinionated solutions.

So why not release your recipe function as its own package?

[trekinbami]

So why not release your recipe function as its own package?

That was definitely the second course of action. Just wanted to make sure that Recipes itself wasn't interested, or this is out of scope of what they're trying to do.

It's a shame to have such a scattered landscape of Vanilla Extract extensions, and no way to find them.

[trekinbami]

Decided to just package it myself. Closing this one. For the ones interested: https://www.npmjs.com/package/responsive-recipes

[yyyyaaa]

thanks for open-sourcing it!