classname-variants 1.4.0 → 1.5.0

package/README.md

@@ -2,6 +2,16 @@
 
 Library to create type-safe components that render their class name based on a set of variants.
 
+## Features
+
+- ⚛️ Supports React, Preact and vanilla DOM
+- 🛡️ Fully type-safe and excellent auto completion support
+- ✅ Supports both optional and required variants
+- 🔗 Supports custom strategies like [tailwind-merge](https://www.npmjs.com/package/tailwind-merge)
+- 🪶 [Light-weight](https://bundlephobia.com/package/classname-variants) without any dependencies
+
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/classname-variants)
+
 # Examples
 
 Here is an example that uses React and Tailwind CSS:
@@ -138,7 +148,7 @@ The `compoundVariants` option can be used to apply class names based on a combin
 
 ### Default variants
 
-You can use the `defaultVariants` property to set defaults:
+If you define a variant it becomes a required prop unless you specify a default (or the variant is boolean). You can use the `defaultVariants` property to specify defaults:
 
 ```ts
 {
@@ -223,6 +233,23 @@ The component can then be rendered as button or as anchor or even as custom comp
 </>
 ```
 
+### Using a custom strategy to combine class names
+
+The built-in strategy for combining multiple class names into one string is simple and straightforward:
+
+```ts
+(classes) => classes.filter(Boolean).join(" ");
+```
+
+If you [want](https://github.com/dcastil/tailwind-merge/blob/main/docs/when-and-how-to-use-it.md), you can use a custom strategy like tailwind-merge instead:
+
+```ts
+import { classNames } from "classname-variants";
+import { twMerge } from "tailwind-merge";
+
+classNames.combine = twMerge;
+```
+
 # Tailwind IntelliSense
 
 In order to get auto-completion for the CSS classes themselves, you can use the [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) plugin for VS Code. In order to make it recognize the strings inside your variants-config, you have to somehow mark them and configure the plugin accordingly.

package/lib/example/preact.d.ts

@@ -2,7 +2,7 @@
 import { h } from "preact";
 export declare const ExpectErrors: <As extends keyof h.JSX.IntrinsicElements | import("preact").ComponentType<any> = "div">(props: {
     as?: As | undefined;
-} & Omit<import("preact").ComponentProps<As>, "as"> & {
+} & Omit<import("preact").ComponentProps<As>, "as" | "color"> & {
     color: "neutral" | "accent";
 } & {}) => import("preact").VNode<{}> | null;
 export declare function WithErrors(): h.JSX.Element;

package/lib/example/preact.js

@@ -13,6 +13,10 @@ const Button = styled("button", {
             neutral: "bg-slate-500 hover:bg-slate-400",
             accent: "bg-teal-500 hover:bg-teal-400",
         },
+        size: {
+            small: "text-sm",
+            medium: "text-md",
+        },
         outlined: {
             true: "border-2",
         },
@@ -52,16 +56,17 @@ export const ExpectErrors = styled("div", {
 });
 export function WithErrors() {
     return (h("div", null,
-        h(Button, { foo: true }, "unknown property"),
+        h(Button, { foo: true, size: "medium" }, "unknown property"),
         h(Card, { foo: true }, "Unknown property"),
-        h(Button, { color: "foo" }, "Invalid variant")));
+        h(Button, { size: "medium", color: "foo" }, "Invalid variant"),
+        h(Button, null, "Missing size")));
 }
 export function PreactApp() {
     return (h("div", { className: "flex justify-center items-center pt-8 gap-4 flex-wrap" },
-        h(Button, { onClick: console.log }, "Accent"),
-        h(Button, { rounded: true }, "Neutral + Rounded"),
-        h(Button, { color: "accent", outlined: true }, "Accent + Outlined"),
-        h(Button, { color: "accent", disabled: true }, "Disabled"),
+        h(Button, { size: "medium", onClick: console.log }, "Accent"),
+        h(Button, { size: "medium", rounded: true }, "Neutral + Rounded"),
+        h(Button, { size: "medium", color: "accent", outlined: true }, "Accent + Outlined"),
+        h(Button, { size: "medium", color: "accent", disabled: true }, "Disabled"),
         h(TitleCard, { title: "Hello" }),
         h(Card, null,
             h("h1", null, "Hello"),

package/lib/example/react.d.ts

@@ -1,7 +1,7 @@
 import React from "react";
 export declare const ExpectErrors: <As extends React.ElementType<any> = "div">(props: {
     as?: As | undefined;
-} & Omit<React.ComponentProps<As>, "as"> & {
+} & Omit<React.ComponentProps<As>, "as" | "color"> & {
     color: "neutral" | "accent";
 } & {}) => React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
 export declare function WithErrors(): JSX.Element;

package/lib/example/react.js

@@ -12,6 +12,10 @@ const Button = styled("button", {
             neutral: "bg-slate-500 hover:bg-slate-400",
             accent: "bg-teal-500 hover:bg-teal-400",
         },
+        size: {
+            small: "text-sm",
+            medium: "text-md",
+        },
         outlined: {
             true: "border-2",
         },
@@ -51,17 +55,18 @@ export const ExpectErrors = styled("div", {
 });
 export function WithErrors() {
     return (React.createElement("div", null,
-        React.createElement(Button, { foo: true }, "unknown property"),
+        React.createElement(Button, { foo: true, size: "medium" }, "unknown property"),
         React.createElement(Card, { foo: true }, "Unknown property"),
-        React.createElement(Button, { color: "foo" }, "Invalid variant"),
+        React.createElement(Button, { size: "medium", color: "foo" }, "Invalid variant"),
+        React.createElement(Button, null, "Missing size"),
         React.createElement(Card, { as: "b", href: "https://example.com" }, "B tags don't have a href attribute")));
 }
 export function ReactApp() {
     return (React.createElement("div", { className: "flex justify-center items-center pt-8 gap-4 flex-wrap" },
-        React.createElement(Button, { onClick: console.log }, "Accent"),
-        React.createElement(Button, { rounded: true }, "Neutral + Rounded"),
-        React.createElement(Button, { color: "accent", outlined: true }, "Accent + Outlined"),
-        React.createElement(Button, { color: "accent", disabled: true }, "Disabled"),
+        React.createElement(Button, { size: "medium", onClick: console.log }, "Accent"),
+        React.createElement(Button, { size: "medium", rounded: true }, "Neutral + Rounded"),
+        React.createElement(Button, { size: "medium", color: "accent", outlined: true }, "Accent + Outlined"),
+        React.createElement(Button, { size: "medium", color: "accent", disabled: true }, "Disabled"),
         React.createElement(TitleCard, { title: "Hello" }),
         React.createElement(Card, null,
             React.createElement("h1", null, "Hello"),

package/lib/index.d.ts

@@ -101,6 +101,9 @@ export type VariantOptions<C extends VariantsConfig<V>, V extends Variants = C["
 export type Simplify<T> = {
     [K in keyof T]: T[K];
 };
+export declare const classNames: {
+    combine: (...classes: Array<string | undefined | null | false | 0>) => string;
+};
 export declare function variants<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): (props: VariantOptions<C>) => string;
 /**
  * No-op function to mark template literals as tailwind strings.

package/lib/index.js

@@ -1,3 +1,6 @@
+export const classNames = {
+    combine: (...classes) => classes.filter(Boolean).join(" "),
+};
 export function variants(config) {
     const { base, variants, compoundVariants, defaultVariants } = config;
     const isBooleanVariant = (name) => {
@@ -6,7 +9,7 @@ export function variants(config) {
     };
     return (props) => {
         var _a;
-        const res = [base];
+        const classes = base ? [base] : [];
         const getSelected = (name) => {
             var _a, _b;
             return (_b = (_a = props[name]) !== null && _a !== void 0 ? _a : defaultVariants === null || defaultVariants === void 0 ? void 0 : defaultVariants[name]) !== null && _b !== void 0 ? _b : (isBooleanVariant(name) ? false : undefined);
@@ -14,15 +17,15 @@ export function variants(config) {
         for (let name in variants) {
             const selected = getSelected(name);
             if (selected !== undefined)
-                res.push((_a = variants[name]) === null || _a === void 0 ? void 0 : _a[selected]);
+                classes.push((_a = variants[name]) === null || _a === void 0 ? void 0 : _a[selected]);
         }
         for (let { variants, className } of compoundVariants !== null && compoundVariants !== void 0 ? compoundVariants : []) {
             const isSelected = (name) => getSelected(name) === variants[name];
             if (Object.keys(variants).every(isSelected)) {
-                res.push(className);
+                classes.push(className);
             }
         }
-        return res.filter(Boolean).join(" ");
+        return classNames.combine(...classes);
     };
 }
 /**

package/lib/preact.d.ts

@@ -19,16 +19,8 @@ type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
-type PolymorphicComponentProps<T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as">;
-export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C, C["variants"]>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: AsProps<As> & Omit<ComponentProps<As>, "as"> & (C["variants"] extends infer T_1 extends Variants ? { [K in keyof T_1 as K extends keyof (C["variants"] extends infer T_2 extends Variants ? { [K_1 in keyof T_2 as C["variants"][K_1] extends {
-    true: any;
-} | {
-    false: any;
-} ? K_1 : never]: C["variants"][K_1]; } : never) | keyof (C["variants"] extends infer T_3 extends Variants ? { [K_2 in keyof T_3 as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } : never) ? never : K]: (C["variants"] extends infer T_4 extends Variants ? { [K_3 in keyof T_4]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; } : never)[K]; } : never) & (C["variants"] extends infer T_5 extends Variants ? { [K_4 in keyof T_5 as K_4 extends keyof (C["variants"] extends infer T_2 extends Variants ? { [K_1 in keyof T_2 as C["variants"][K_1] extends {
-    true: any;
-} | {
-    false: any;
-} ? K_1 : never]: C["variants"][K_1]; } : never) | keyof (C["variants"] extends infer T_3 extends Variants ? { [K_2 in keyof T_3 as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } : never) ? K_4 : never]?: (C["variants"] extends infer T_4 extends Variants ? { [K_3 in keyof T_4]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; } : never)[K_4] | undefined; } : never)) => VNode | null;
+type PolymorphicComponentProps<V, T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as" | keyof V> & V;
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C, C["variants"]>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: PolymorphicComponentProps<VariantOptions<C, C["variants"]>, As>) => VNode | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/preact.js

@@ -1,6 +1,6 @@
 import { h } from "preact";
 import { forwardRef } from "preact/compat";
-import { variants, } from "./index.js";
+import { variants, classNames, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
@@ -12,9 +12,7 @@ export function variantProps(config) {
             }
         }
         // Add the optionally passed class/className prop for chaining
-        result.class = [variantClassName(props), props.class, props.className]
-            .filter(Boolean)
-            .join(" ");
+        result.class = classNames.combine(variantClassName(props), props.class, props.className);
         return result;
     };
 }

package/lib/react.d.ts

@@ -17,16 +17,8 @@ type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
-type PolymorphicComponentProps<T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as">;
-export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C, C["variants"]>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: AsProps<As> & Omit<ComponentProps<As>, "as"> & (C["variants"] extends infer T_1 extends Variants ? { [K in keyof T_1 as K extends keyof (C["variants"] extends infer T_2 extends Variants ? { [K_1 in keyof T_2 as C["variants"][K_1] extends {
-    true: any;
-} | {
-    false: any;
-} ? K_1 : never]: C["variants"][K_1]; } : never) | keyof (C["variants"] extends infer T_3 extends Variants ? { [K_2 in keyof T_3 as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } : never) ? never : K]: (C["variants"] extends infer T_4 extends Variants ? { [K_3 in keyof T_4]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; } : never)[K]; } : never) & (C["variants"] extends infer T_5 extends Variants ? { [K_4 in keyof T_5 as K_4 extends keyof (C["variants"] extends infer T_2 extends Variants ? { [K_1 in keyof T_2 as C["variants"][K_1] extends {
-    true: any;
-} | {
-    false: any;
-} ? K_1 : never]: C["variants"][K_1]; } : never) | keyof (C["variants"] extends infer T_3 extends Variants ? { [K_2 in keyof T_3 as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } : never) ? K_4 : never]?: (C["variants"] extends infer T_4 extends Variants ? { [K_3 in keyof T_4]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; } : never)[K_4] | undefined; } : never)) => ReactElement | null;
+type PolymorphicComponentProps<V, T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as" | keyof V> & V;
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C, C["variants"]>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: PolymorphicComponentProps<VariantOptions<C, C["variants"]>, As>) => ReactElement | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/react.js

@@ -1,5 +1,5 @@
 import { createElement, forwardRef, } from "react";
-import { variants, } from "./index.js";
+import { variants, classNames, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
@@ -11,9 +11,7 @@ export function variantProps(config) {
             }
         }
         // Add the optionally passed className prop for chaining
-        result.className = [variantClassName(props), props.className]
-            .filter(Boolean)
-            .join(" ");
+        result.className = classNames.combine(variantClassName(props), props.className);
         return result;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",