API Reference

API Reference

api.ts
 
const buttonBase = vs({
    base: styles.btnBase
});
 
 
const config = {
    // (1) extending the styles from another `vs`
    extend: buttonBase,
    // (2) default styles that are allways applied
    base: styles.btn,
    // (3) variants for this component-styles
    variants: {
        color: {
          primary: styles.primary, // (4) can be an array also
          secondary: styles.secondary
        },
        size: {
            small: styles.small,
            medium: styles.medium
        }
    },
    // (5) default values of variant to use when value is not passed (10)
    defaultVariants: {
        // (6) default value for `color` variant is `primary`
        color: "primary"
    },
    // (7) If combination of variant occur matching certain values what additional styles should be applied
    compoundVariants: [
        // (8) styles to apply in extra when combination of variant matches color="primary" and size="small"
        {
            variants: {
                color: "primary",
                size:  "small"
            },
            styles: styles.primarySmallExtra
        }
        // (9) styles to apply in extra when combination of variant matches color="primary" and size="medium"
        {
            variants: {
                color: "primary",
                size:  "medium"
            },
            styles: styles.primaryMediumExtra
        }
    ]
};
 
// (10): `vs` return a component-styles function calling which with variant-values (11) gives styles array 
const button = vs(config);
 
// (11) `component-styles` called with variant values return array of styles (12).
const styles = button({ size: "small" })
 
// (12) returned styles can be process accordingly (13)
/*
[
 // extended styles from baseButton
 styles.btnBase, 
 // base styles of button
 styles.btn,
 // default variant value of button color is primary
 styles.primary,
 // variant value supplied to `component-styles`
 styles.small
 // Note: `compoundVariants[0]` wasn't applied as `compoundVariants` needs all required variants values to be explicitly passed in 
 // component-styles, they don't assume values from `defaultVariants`
]
*/
 
// (13) returned styles need to be processed according to framework in question
// if `styles-modules` or `tailwind` are used which classes 
// we can use `clsx` to combine all applicable variant classes
const className = clsx(styles); 
// if using css-in-js
const className = css(styles);
// this final className can be applied on component to give styling (14)
 
// (14) using the final className
<button className={className}>...</button>
  1. extend: A variant-styles(vs) can extend any other variant styles. This helps in making component styles as composition.
  2. base: Every variant-styles(vs) has base or default styles that can be applied to them.
  3. variants: Variants that this component-styles will support.
  4. values for the variant can be array also i.e primary: [styles.primaryText, styles.primaryBg]
  5. defaultVariants: These are variant values to be used when the there values are not supplied to component-style.
  6. In this example on line (11) missing color variant was assumed from defaultVariants i.e color="primary".
  7. compoundVariants: If combination of variant occurs and when such a combination is met we want to add more styles then these compoundVariants are usefull.
  8. We can list all variants conditions that must be met for this compoundVariants styles to be active. These extra styles primaryMediumExtra are applied when color="primary" and size="medium".
  9. More combination of compoundVariants.
  10. vs for a given config returns component-styles.
  11. component-styles are function that takes in combination of variants and for these variant a cumulative styles array is returned.
  12. This array is an example of all styles applicable when size="small" is used.
  13. Now that we have evaluted which styles are applicable for current values of variants passed to component-styles. These returned styles need to be processed according to the styling framework in use.
  14. The processed styles is a className which can be used on your components.
Tailwind