postcss-cva

postcss-cva

A postcss plugin that generates cva functions based on comments

What is cva (class-variance-authority)?

The CVA function is an excellent atomic tool function, refer to https://cva.style/docs

Concept

For example. A cva function consists of 4 parts: base,variants,compoundVariants,defaultVariants

import { cva } from 'class-variance-authority'
//                     ⬇️ base
const button = cva(['font-semibold', 'border', 'rounded'], {
  // ⬇️ variants
  variants: {
    intent: {
      primary: ['bg-blue-500', 'text-white', 'border-transparent', 'hover:bg-blue-600'],
      secondary: ['bg-white', 'text-gray-800', 'border-gray-400', 'hover:bg-gray-100']
    },
    size: {
      small: ['text-sm', 'py-1', 'px-2'],
      medium: ['text-base', 'py-2', 'px-4']
    }
  },
  // ⬇️ compoundVariants
  compoundVariants: [
    {
      intent: 'primary',
      size: 'medium',
      class: 'uppercase'
    }
  ],
  // ⬇️ defaultVariants
  defaultVariants: {
    intent: 'primary',
    size: 'medium'
  }
})

button()
// => "font-semibold border rounded bg-blue-500 text-white border-transparent hover:bg-blue-600 text-base py-2 px-4 uppercase"

button({ intent: 'secondary', size: 'small' })
// => "font-semibold border rounded bg-white text-gray-800 border-gray-400 hover:bg-gray-100 text-sm py-1 px-2"

Usage

For example, in this plugin

type="primary" is called query, ["shadow-sm"] is called params

The same query will be merged with params together

Note ⚠ ️: If you use scss, you can use the // below for comment, otherwise please use /* */

/* @meta path="button" */
.btn {
  /* @b */
}
.btn-primary {
  /* @v type="primary" */
}
.btn-xs {
  /* @v size="xs" */
}
.uppercase {
  /* @cv type="primary" size="xs" */
}
/* @dv type="primary" */

/* @gb ["rounded"] */
/* @gv type="primary" ["shadow-sm"] */
/* @gcv type="primary" size="xs" ["p-1"] */

will generate:

import { cva, VariantProps } from 'class-variance-authority'
//                 @b and @gb
const index = cva(['btn', 'rounded'], {
  variants: {
    // @v type="primary" and @dv type="primary"
    type: {
      primary: ['btn-primary', 'shadow-sm']
    },
    // @v size="xs"
    size: {
      xs: ['btn-xs']
    }
  },
  // @cv type="primary" size="xs" and @gcv type="primary" size="xs" ["p-1"]
  compoundVariants: [
    {
      class: ['uppercase', 'p-1'],
      type: ['primary'],
      size: ['xs']
    }
  ],
  // @dv type="primary"
  defaultVariants: {
    type: 'primary'
  }
})
export type Props = VariantProps<typeof index>
export default index

References

keyword	param	type	description
@b	base	node	add current node selector to base
@v	variants	node	add current node selector to variants
@cv	compoundVariants	node	add current node selector to compoundVariants
@dv	defaultVariants	global	define defaultVariants
@gb	base	global	define base
@gv	variants	global	define variants
@gcv	compoundVariants	global	define defaultVariants
@meta	meta	global	define metadata

@meta query:

/* @meta path="{your-cva-filepath}" format="ts/js" */

You can use the js variables to dynamically generate functions

Type explain

node

Get the last class node in the current selector and add it to the corresponding results

global

It will not be calculated based on the defined position. It can be defined anywhere. The one defined later will overwrite the one defined before.

Options

outdir

Type: string Default: cva

The location of the output directory

importFrom

Type: string Default: class-variance-authority

From which package to import the cva function

dryRun

Type: boolean Default: false

cwd

Type: string Default: process.cwd()

format

Type: js | ts Default: ts

prefix

Type: string Default: ''

License

MIT License © 2023-PRESENT sonofmagic