Making a custom `group-`/`peer-` `matchVariant()` plugin breaks `group-[]:`/`peer-[]:` syntax

[MichaelAllenWarner]

What version of Tailwind CSS are you using?

For example: v3.3.3

Reproduction URL

https://play.tailwindcss.com/0w4BOsCoTI

Describe your issue

Custom group-/peer- matchVariant() plugins break Tailwind's ability to correctly handle arbitrary-selector group-/peer- utilities.

A possible solution is to have this code run again after registering a user's custom plugins (but without the third argument to the matchVariant() call). That's how I hack around the problem in my projects at the moment, anyway.

[thecrypticace]

Hey, so there's a few things to explain here:

1. Only a single variant can exist with any given "name"
2. matchVariant with a set of values registers a variant for a given name and, for each value, each name-key pair. For example, a call to matchVariant('group', …, {values: {foo: '', bar: ''}} registers variants for group, group-foo, and group-bar. This is an implementation detail but it's important to know alongside the next point.
3. If you register a variant that already exists then it is replaced
4. When using matchVariant you are responsible for handling the arbitrary values

Let's take a look at an updated version of the code and how it works. And further down we'll look at a potentially better solution for your usecase.

To set this up a custom group to handle your custom hocus value and arbitrary values for the variant you need to tweak the code a bit. I'll inline details in the comments in the code itself.

// group-hocus / group-hocus/{name}
matchVariant(
  'group',
  (value, { modifier }) => {
    // This is intended to preserve array-based values from the `values` key as-is
    // while also allowing us to handle string-based values in a consistent manner
    let values = Array.isArray(value) ? value : [value]
    
    // Like before, we generate a selector for each of `:hover`, `:focus`,
    // or other values from the `values` key _and_ now, from the given arbitrary value
    // Now this code is _far_ simpler than what we have because we handle
    // a number of edge cases around selectors, how `:visited` works, etc…
    // Should you need to handle those edge cases
    // then this code will get a bit more complex
    return values.map(value =>
      // Generate the selector based on whether or not a modifier is present
      modifier
        ? `:merge(.group\\/${modifier})${value} &`
        : `:merge(.group)${value} &`
    )
  },
  { 
    // Here we specify the selectors to use. Note that you're going to have
    // to also include all of the Tailwind included ones yourself as well
    values: {
      hocus: [":hover", ":focus"],
      active: ":active",
      hover: ":hover",
      focus: ":focus",
      // … etc
    }
  },
);

In general, if you're using matchVariant and NOT handling the value key then arbitrary values are NOT going to work. There's little reason to ignore the value key in matchVariant unless you never expect it to handle other values. I'm going to talk about one such case below.

Given that, let's look at a version that is a bit more suited for your case. It's similar but doesn't require overriding the existing group variant. Note that sorting won't be exactly the same but It seems like, what you want the most is to add a group-hocus and group-hocus/modifier variants (and the peer versions as well). I would instead register these as group-hocus via matchVariant with a DEFAULT key.

// group-hocus / group-hocus/{name}
matchVariant(
  'group-hocus',
  // Note that I'm now ignoring the value because I don't ever expect to write group-hocus-[anything]
  (_, { modifier }) => {
    return values.map(value =>
      // Generate the selector based on whether or not a modifier is present
      modifier
        ? `:merge(.group\\/${modifier})${value} &`
        : `:merge(.group)${value} &`
    )
  },
  { 
    // The `DEFAULT` key here exists so `group-hocus` will work by itself.
    values: { DEFAULT: '' }
  },
);

I've prepped a Tailwind Play for you here: https://play.tailwindcss.com/rhSc7Ys90N

Let me know if you have any more questions.

Hope that helps! ✨

[MichaelAllenWarner]

Wow, @thecrypticace -- thank you so much for taking the time to write all of that up. Incredibly helpful.

I'd previously tried registering group-whatever and peer-whatever, but I was missing the values: { DEFAULT: '' } step and therefore could never get it to work. That entirely solves my problem!