classname-variants 1.6.0 → 1.7.0

package/README.md

@@ -188,6 +188,49 @@ import { styled } from "classname-variants/react";
 const Button = styled("button", "bg-transparent border p-2");
 ```
 
+### Default props
+
+If your underlying element (or custom component) expects props that you want to
+provide automatically, you can use the `defaultProps` option. All defaulted
+props become optional in TypeScript – even when you later render the component
+with a polymorphic `as` prop.
+
+```tsx
+const Button = styled("button", {
+  base: "inline-flex items-center gap-2",
+  defaultProps: {
+    type: "button",
+  },
+});
+
+// `type` is optional but still overridable
+<Button />;
+<Button type="submit" />;
+
+// Works together with `as`
+<Button as="a" href="/docs" />;
+```
+
+### Forwarding props
+
+When a variant mirrors an existing prop (such as `disabled` on a button), add
+it to `forwardProps` so the resolved value is passed through to the rendered
+element or custom component.
+
+```tsx
+const Button = styled("button", {
+  variants: {
+    disabled: {
+      true: "cursor-not-allowed",
+    },
+  },
+  forwardProps: ["disabled"],
+});
+
+// Renders with both the class name and the DOM `disabled` prop applied.
+<Button disabled />;
+```
+
 ### Styling custom components
 
 You can style any custom React/Preact component as long as they accept a `className` prop (or `class` in case of Preact).
@@ -270,11 +313,7 @@ const button = variants({
 });
 ```
 
-You can then add the following line to your `settings.json`:
-
-```
-"tailwindCSS.experimental.classRegex": ["tw`(.+?)`"]
-```
+You can then set the _Tailwind CSS: Class Functions_ option to `tw`.
 
 > [!NOTE]
 > The `tw` helper function is just an alias for [`String.raw()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw) which has the nice side effect backslashes are not treated as [escape character in JSX](https://tailwindcss.com/docs/adding-custom-styles#handling-whitespace).

package/biome.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": {
+          "options": {},
+          "level": "warn",
+          "fix": "safe"
+        }
+      },
+      "complexity": {
+        "noBannedTypes": "off"
+      },
+      "style": {
+        "noNonNullAssertion": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedAttributes": "on"
+      }
+    }
+  }
+}

package/lib/example/index.js

@@ -1,8 +1,8 @@
+import { h, render } from "preact";
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
-import { render, h } from "preact";
-import { ReactApp } from "./react";
 import { PreactApp } from "./preact";
+import { ReactApp } from "./react";
 const root = createRoot(document.getElementById("react-root"));
 root.render(createElement(ReactApp));
 render(h(PreactApp, {}), document.getElementById("preact-root"));

package/lib/example/preact.js

@@ -1,11 +1,17 @@
 /** @jsx h */
-import { styled } from "../preact";
+// biome-ignore lint/correctness/noUnusedImports: Preact JSX pragma requires importing h
 import { h } from "preact";
+import { styled } from "../preact";
 function CustomComponent({ title, ...props }) {
     return h("div", { ...props }, title);
 }
 const Card = styled("div", "bg-white p-4 border-2 rounded-lg");
-const TitleCard = styled(CustomComponent, "bg-white p-4 border-2 rounded-lg");
+const TitleCard = styled(CustomComponent, {
+    base: "bg-white p-4 border-2 rounded-lg",
+    defaultProps: {
+        title: "Default Title",
+    },
+});
 const Button = styled("button", {
     base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
     variants: {
@@ -24,6 +30,9 @@ const Button = styled("button", {
             true: "rounded-full",
             false: "rounded-sm",
         },
+        disabled: {
+            true: "cursor-not-allowed",
+        },
     },
     compoundVariants: [
         {
@@ -34,6 +43,10 @@ const Button = styled("button", {
     defaultVariants: {
         color: "neutral",
     },
+    defaultProps: {
+        type: "button",
+    },
+    forwardProps: ["disabled"],
 });
 export const ExpectErrors = styled("div", {
     variants: {
@@ -53,20 +66,25 @@ export const ExpectErrors = styled("div", {
         //@ts-expect-error
         outlined: true,
     },
+    forwardProps: [
+        //@ts-expect-error
+        "outlined",
+    ],
 });
 export function WithErrors() {
     return (h("div", null,
         h(Button, { foo: true, size: "medium" }, "unknown property"),
         h(Card, { foo: true }, "Unknown property"),
-        h(Button, { size: "medium", color: "foo" }, "Invalid variant"),
+        h(Button, { color: "foo", size: "medium" }, "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, { size: "medium", onClick: console.log }, "Neutral"),
-        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(Button, { onClick: console.log, size: "medium" }, "Neutral"),
+        h(Button, { rounded: true, size: "medium" }, "Neutral + Rounded"),
+        h(Button, { color: "accent", outlined: true, size: "medium" }, "Accent + Outlined"),
+        h(Button, { color: "accent", disabled: true, size: "medium" }, "Disabled"),
+        h(TitleCard, null),
         h(TitleCard, { title: "Hello" }),
         h(Card, null,
             h("h1", null, "Hello"),

package/lib/example/react.d.ts

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

package/lib/example/react.js

@@ -1,10 +1,17 @@
+// biome-ignore lint/correctness/noUnusedImports: React import required for JSX runtime configuration
 import React from "react";
 import { styled } from "../react";
 function CustomComponent({ title, ...props }) {
     return React.createElement("div", { ...props }, title);
 }
 const Card = styled("div", "bg-white p-4 border-2 rounded-lg");
-const TitleCard = styled(CustomComponent, "bg-white p-4 border-2 rounded-lg");
+const _cardAsShouldBeGeneric = "a";
+const TitleCard = styled(CustomComponent, {
+    base: "bg-white p-4 border-2 rounded-lg",
+    defaultProps: {
+        title: "Default Title",
+    },
+});
 const Button = styled("button", {
     base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
     variants: {
@@ -23,6 +30,9 @@ const Button = styled("button", {
             true: "rounded-full",
             false: "rounded-sm",
         },
+        disabled: {
+            true: "cursor-not-allowed",
+        },
     },
     compoundVariants: [
         {
@@ -33,6 +43,10 @@ const Button = styled("button", {
     defaultVariants: {
         color: "neutral",
     },
+    defaultProps: {
+        type: "button",
+    },
+    forwardProps: ["disabled"],
 });
 export const StyledWithoutVariants = styled("div", {
     base: "bg-white",
@@ -58,21 +72,26 @@ export const ExpectErrors = styled("div", {
         //@ts-expect-error
         outlined: true,
     },
+    forwardProps: [
+        //@ts-expect-error
+        "outlined",
+    ],
 });
 export function WithErrors() {
     return (React.createElement("div", null,
         React.createElement(Button, { foo: true, size: "medium" }, "unknown property"),
         React.createElement(Card, { foo: true }, "Unknown property"),
-        React.createElement(Button, { size: "medium", color: "foo" }, "Invalid variant"),
+        React.createElement(Button, { color: "foo", size: "medium" }, "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, { size: "medium", onClick: console.log }, "Neutral"),
-        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(Button, { onClick: console.log, size: "medium" }, "Neutral"),
+        React.createElement(Button, { rounded: true, size: "medium" }, "Neutral + Rounded"),
+        React.createElement(Button, { color: "accent", outlined: true, size: "medium" }, "Accent + Outlined"),
+        React.createElement(Button, { color: "accent", disabled: true, size: "medium" }, "Disabled"),
+        React.createElement(TitleCard, null),
         React.createElement(TitleCard, { title: "Hello" }),
         React.createElement(Card, null,
             React.createElement("h1", null, "Hello"),

package/lib/index.d.ts

@@ -21,6 +21,7 @@ export interface VariantsConfig<V extends Variants = {}> {
     variants: V;
     compoundVariants?: CompoundVariant<V>[];
     defaultVariants?: Partial<OptionsOf<V>>;
+    forwardProps?: ReadonlyArray<Extract<keyof V, string>>;
 }
 /**
  * Rules for class names that are applied for certain variant combinations.

package/lib/index.js

@@ -14,12 +14,12 @@ export function variants(config) {
             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);
         };
-        for (let name in variants) {
+        for (const name in variants) {
             const selected = getSelected(name);
             if (selected !== undefined)
                 classes.push((_a = variants[name]) === null || _a === void 0 ? void 0 : _a[selected]);
         }
-        for (let { variants, className } of compoundVariants !== null && compoundVariants !== void 0 ? compoundVariants : []) {
+        for (const { variants, className } of compoundVariants !== null && compoundVariants !== void 0 ? compoundVariants : []) {
             const isSelected = (name) => getSelected(name) === variants[name];
             if (Object.keys(variants).every(isSelected)) {
                 classes.push(className);

package/lib/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/index.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { classNames, tw, variants } from "./index.js";
+describe("classNames.combine", () => {
+    it("joins truthy values with spaces", () => {
+        expect(classNames.combine("foo", undefined, "bar", false, "baz")).toBe("foo bar baz");
+    });
+    it("returns empty string for falsy input", () => {
+        expect(classNames.combine(undefined, null, false, 0)).toBe("");
+    });
+});
+describe("tw helper", () => {
+    it("returns raw template strings", () => {
+        expect(tw `foo`).toBe("foo");
+        const dynamic = "bar";
+        expect(tw `foo-${dynamic}`).toBe("foo-bar");
+    });
+});
+describe("variants factory", () => {
+    const config = {
+        base: "btn",
+        variants: {
+            tone: {
+                neutral: "text-neutral",
+                accent: "text-accent",
+            },
+            size: {
+                small: "text-sm",
+                large: "text-lg",
+            },
+            disabled: {
+                true: "opacity-50",
+                false: "opacity-100",
+            },
+        },
+        defaultVariants: {
+            tone: "neutral",
+            size: "small",
+        },
+        compoundVariants: [
+            {
+                variants: { tone: "accent", size: "large" },
+                className: "text-accent-large",
+            },
+            {
+                variants: { disabled: true },
+                className: "pointer-events-none",
+            },
+        ],
+    };
+    const button = variants(config);
+    it("includes base class", () => {
+        expect(button({ tone: "neutral", size: "small" })).toContain("btn");
+    });
+    it("uses default variants when omitted", () => {
+        const result = button({});
+        expect(result).toContain("text-neutral");
+        expect(result).toContain("text-sm");
+        expect(result).not.toContain("text-lg");
+    });
+    it("applies boolean variants with false default", () => {
+        const result = button({});
+        expect(result).toContain("opacity-100");
+    });
+    it("prefers explicit props over defaults", () => {
+        const result = button({ tone: "accent", size: "large" });
+        expect(result).toContain("text-accent");
+        expect(result).toContain("text-lg");
+        expect(result).not.toContain("text-neutral");
+        expect(result).not.toContain("text-sm");
+    });
+    it("handles boolean true variants", () => {
+        const result = button({ disabled: true });
+        expect(result).toContain("opacity-50");
+        expect(result).toContain("pointer-events-none");
+    });
+    it("runs compound variants only when all predicates match", () => {
+        const accentLarge = button({ tone: "accent", size: "large" });
+        expect(accentLarge).toContain("text-accent-large");
+        const accentSmall = button({ tone: "accent", size: "small" });
+        expect(accentSmall).not.toContain("text-accent-large");
+    });
+    it("accepts boolean variants via explicit false", () => {
+        const result = button({ disabled: false });
+        expect(result).toContain("opacity-100");
+        expect(result).not.toContain("pointer-events-none");
+    });
+    it("keeps default class when variant explicitly undefined", () => {
+        const result = button({ tone: undefined, size: "large" });
+        expect(result).toContain("text-lg");
+        expect(result).toContain("text-neutral");
+        expect(result).not.toContain("text-accent");
+    });
+});

package/lib/preact.d.ts

@@ -1,6 +1,6 @@
-import type { JSX, ComponentType, ComponentProps, VNode } from "preact";
+import type { ComponentProps, ComponentType, JSX, VNode } from "preact";
 type ElementType<P = any> = keyof JSX.IntrinsicElements | ComponentType<P>;
-import { Variants, VariantsConfig, VariantOptions, Simplify } from "./index.js";
+import { type Simplify, type VariantOptions, type Variants, type VariantsConfig } from "./index.js";
 /**
  * Utility type to infer the first argument of a variantProps function.
  */
@@ -12,22 +12,40 @@ type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"
     class?: string;
     className?: string;
 };
+type ForwardedVariantKeys<C> = C extends {
+    forwardProps?: ReadonlyArray<infer K>;
+    variants: infer V;
+} ? Extract<K, keyof V> : never;
+type VariantPropKeys<C> = C extends {
+    variants: infer V;
+} ? keyof V : never;
+type ForwardedVariantProps<C extends VariantsConfig<any>> = Pick<VariantOptions<C>, ForwardedVariantKeys<C>>;
 export declare function variantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): <P extends VariantProps<C, C["variants"]>>(props: P) => {
     class: string;
-} & Omit<P, keyof C["variants"]>;
-type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
+} & Omit<P, VariantPropKeys<C>> & ForwardedVariantProps<C>;
+type VariantsOf<T> = T extends {
+    variants: infer TV;
+} ? TV extends Variants ? TV : {} : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
+type CleanDefaults<Defaults> = Exclude<Defaults, undefined>;
+type DefaultedKeys<Props, Defaults> = Extract<keyof CleanDefaults<Defaults>, keyof Props>;
+type WithDefaultProps<Props, Defaults> = [CleanDefaults<Defaults>] extends [
+    never
+] ? Props : Omit<Props, DefaultedKeys<Props, Defaults>> & Partial<Pick<Props, DefaultedKeys<Props, Defaults>>>;
 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 | {
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C>, Defaults extends Partial<ComponentProps<T>> | undefined = undefined>(type: T, config: string | {
     base: string;
-} | Simplify<C>): <As extends ElementType = T>(props: PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
+    defaultProps?: Defaults;
+} | (Simplify<C> & {
+    defaultProps?: Defaults;
+})): <As extends ElementType = T>(props: WithDefaultProps<PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
     base: string;
     variants?: undefined;
     compoundVariants?: undefined;
     defaultVariants?: undefined;
-} ? {} : VariantOptions<C>, As>) => VNode | null;
+} ? {} : VariantOptions<C>, As>, Defaults>) => VNode | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/preact.js

@@ -1,16 +1,31 @@
 import { h } from "preact";
 import { forwardRef } from "preact/compat";
-import { variants, classNames, } from "./index.js";
+import { classNames, variants, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
         const result = {};
         // Pass-through all unrelated props
-        for (let prop in props) {
+        for (const prop in props) {
             if (config.variants && !(prop in config.variants)) {
                 result[prop] = props[prop];
             }
         }
+        if (config.forwardProps) {
+            for (const name of config.forwardProps) {
+                if (!config.variants || !(name in config.variants))
+                    continue;
+                if (Object.hasOwn(props, name)) {
+                    result[name] = props[name];
+                    continue;
+                }
+                if (config.defaultVariants &&
+                    Object.hasOwn(config.defaultVariants, name)) {
+                    result[name] =
+                        config.defaultVariants[name];
+                }
+            }
+        }
         // Add the optionally passed class/className prop for chaining
         result.class = classNames.combine(variantClassName(props), props.class, props.className);
         return result;
@@ -21,9 +36,26 @@ export function styled(type, config) {
         ? variantProps({ base: config, variants: {} })
         : "variants" in config
             ? variantProps(config)
-            : variantProps({ base: config.base, variants: {} });
+            : variantProps({
+                base: config
+                    .base,
+                variants: {},
+            });
+    const defaultProps = typeof config === "string" ? undefined : config.defaultProps;
+    const toRecord = (value) => value && typeof value === "object"
+        ? value
+        : {};
+    const readClass = (value) => typeof value === "string" ? value : undefined;
     const Component = forwardRef(({ as, ...props }, ref) => {
-        return h(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
+        const defaultsRecord = toRecord(defaultProps);
+        const propsRecord = props;
+        const merged = {
+            ...defaultsRecord,
+            ...propsRecord,
+        };
+        merged.class = classNames.combine(readClass(defaultsRecord.class), readClass(propsRecord.class));
+        merged.className = classNames.combine(readClass(defaultsRecord.className), readClass(propsRecord.className));
+        return h(as !== null && as !== void 0 ? as : type, { ...styledProps(merged), ref });
     });
     return Component;
 }

package/lib/preact.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/preact.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { variantProps } from "./preact.js";
+describe("preact adapter forwardProps", () => {
+    it("forwards explicit variant values", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+                size: {
+                    small: "text-sm",
+                    large: "text-lg",
+                },
+            },
+            defaultVariants: {
+                size: "small",
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({
+            disabled: true,
+            size: "large",
+            class: "custom",
+        });
+        expect(result.disabled).toBe(true);
+        expect(result.class).toContain("btn");
+        expect(result.class).toContain("opacity-50");
+        expect(result.class).toContain("text-lg");
+        expect(result.class).toContain("custom");
+        expect("size" in result).toBe(false);
+    });
+    it("uses default variant values when forwarding", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+            },
+            defaultVariants: {
+                disabled: true,
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({});
+        expect(result.disabled).toBe(true);
+        expect(result.class).toContain("opacity-50");
+    });
+});

package/lib/react.d.ts

@@ -1,5 +1,5 @@
-import { ComponentProps, ElementType, ReactElement } from "react";
-import { Variants, VariantsConfig, VariantOptions, Simplify } from "./index.js";
+import { type ComponentProps, type ElementType, type ReactElement } from "react";
+import { type Simplify, type VariantOptions, type Variants, type VariantsConfig } from "./index.js";
 /**
  * Utility type to infer the first argument of a variantProps function.
  */
@@ -10,22 +10,40 @@ export type VariantPropsOf<T> = T extends (props: infer P) => any ? P : never;
 type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = VariantOptions<C> & {
     className?: string;
 };
+type ForwardedVariantKeys<C> = C extends {
+    forwardProps?: ReadonlyArray<infer K>;
+    variants: infer V;
+} ? Extract<K, keyof V> : never;
+type VariantPropKeys<C> = C extends {
+    variants: infer V;
+} ? keyof V : never;
+type ForwardedVariantProps<C extends VariantsConfig<any>> = Pick<VariantOptions<C>, ForwardedVariantKeys<C>>;
 export declare function variantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): <P extends VariantProps<C, C["variants"]>>(props: P) => {
     className: string;
-} & Omit<P, keyof C["variants"]>;
-type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
+} & Omit<P, VariantPropKeys<C>> & ForwardedVariantProps<C>;
+type VariantsOf<T> = T extends {
+    variants: infer TV;
+} ? TV extends Variants ? TV : {} : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
+type CleanDefaults<Defaults> = Exclude<Defaults, undefined>;
+type DefaultedKeys<Props, Defaults> = Extract<keyof CleanDefaults<Defaults>, keyof Props>;
+type WithDefaultProps<Props, Defaults> = [CleanDefaults<Defaults>] extends [
+    never
+] ? Props : Omit<Props, DefaultedKeys<Props, Defaults>> & Partial<Pick<Props, DefaultedKeys<Props, Defaults>>>;
 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 | {
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C>, Defaults extends Partial<ComponentProps<T>> | undefined = undefined>(type: T, config: string | {
     base: string;
-} | Simplify<C>): <As extends ElementType = T>(props: PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
+    defaultProps?: Defaults;
+} | (Simplify<C> & {
+    defaultProps?: Defaults;
+})): <As extends ElementType = T>(props: WithDefaultProps<PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
     base: string;
     variants?: undefined;
     compoundVariants?: undefined;
     defaultVariants?: undefined;
-} ? {} : VariantOptions<C>, As>) => ReactElement | null;
+} ? {} : VariantOptions<C>, As>, Defaults>) => ReactElement | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/react.js

@@ -1,15 +1,30 @@
 import { createElement, forwardRef, } from "react";
-import { variants, classNames, } from "./index.js";
+import { classNames, variants, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
         const result = {};
         // Pass-through all unrelated props
-        for (let prop in props) {
+        for (const prop in props) {
             if (config.variants && !(prop in config.variants)) {
                 result[prop] = props[prop];
             }
         }
+        if (config.forwardProps) {
+            for (const name of config.forwardProps) {
+                if (!config.variants || !(name in config.variants))
+                    continue;
+                if (Object.hasOwn(props, name)) {
+                    result[name] = props[name];
+                    continue;
+                }
+                if (config.defaultVariants &&
+                    Object.hasOwn(config.defaultVariants, name)) {
+                    result[name] =
+                        config.defaultVariants[name];
+                }
+            }
+        }
         // Add the optionally passed className prop for chaining
         result.className = classNames.combine(variantClassName(props), props.className);
         return result;
@@ -20,9 +35,25 @@ export function styled(type, config) {
         ? variantProps({ base: config, variants: {} })
         : "variants" in config
             ? variantProps(config)
-            : variantProps({ base: config.base, variants: {} });
+            : variantProps({
+                base: config
+                    .base,
+                variants: {},
+            });
+    const defaultProps = typeof config === "string" ? undefined : config.defaultProps;
+    const toRecord = (value) => value && typeof value === "object"
+        ? value
+        : {};
+    const readClassName = (value) => typeof value === "string" ? value : undefined;
     const Component = forwardRef(({ as, ...props }, ref) => {
-        return createElement(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
+        const defaultsRecord = toRecord(defaultProps);
+        const propsRecord = props;
+        const merged = {
+            ...defaultsRecord,
+            ...propsRecord,
+        };
+        merged.className = classNames.combine(readClassName(defaultsRecord.className), readClassName(propsRecord.className));
+        return createElement(as !== null && as !== void 0 ? as : type, { ...styledProps(merged), ref });
     });
     return Component;
 }

package/lib/react.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/react.test.js

@@ -0,0 +1,78 @@
+import * as React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { styled, variantProps } from "./react.js";
+describe("react adapter forwardProps", () => {
+    it("forwards explicit variant values", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+                tone: {
+                    neutral: "text-slate-700",
+                    accent: "text-teal-600",
+                },
+            },
+            defaultVariants: {
+                tone: "neutral",
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({
+            disabled: true,
+            tone: "accent",
+            className: "custom",
+        });
+        expect(result.disabled).toBe(true);
+        expect(result.className).toContain("btn");
+        expect(result.className).toContain("opacity-50");
+        expect(result.className).toContain("text-teal-600");
+        expect(result.className).toContain("custom");
+        expect("tone" in result).toBe(false);
+    });
+    it("uses default variant values when forwarding", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+            },
+            defaultVariants: {
+                disabled: true,
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({});
+        expect(result.disabled).toBe(true);
+        expect(result.className).toContain("opacity-50");
+    });
+    it("renders forwarded props through styled components", () => {
+        const buttonConfig = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+            },
+            forwardProps: ["disabled"],
+        };
+        const Button = styled("button", buttonConfig);
+        const markup = renderToStaticMarkup(React.createElement(Button, {
+            className: "custom",
+            disabled: true,
+        }));
+        const host = document.createElement("div");
+        host.innerHTML = markup;
+        const button = host.querySelector("button");
+        expect(button).not.toBeNull();
+        expect(button.hasAttribute("disabled")).toBe(true);
+        expect(button.className).toContain("btn");
+        expect(button.className).toContain("opacity-50");
+        expect(button.className).toContain("custom");
+    });
+});

package/llms.txt

@@ -15,8 +15,8 @@ This library provides a variant API for generating class names based on componen
 - `tw` - Tagged template literal helper for Tailwind CSS IntelliSense
 
 ### Framework Integrations
-- `src/react.ts` - React-specific bindings with `styled()` and `variantProps()` functions
-- `src/preact.ts` - Preact-specific bindings (similar to React but uses Preact's JSX)
+- `src/react.ts` - React-specific bindings with `styled()` and `variantProps()` functions, including runtime merging and type inference for `defaultProps`
+- `src/preact.ts` - Preact-specific bindings (similar to React but uses Preact's JSX) with equivalent `defaultProps` support
 
 ### Key Features
 - Type-safe variant definitions with full TypeScript inference
@@ -24,7 +24,9 @@ This library provides a variant API for generating class names based on componen
 - Boolean variants (true/false)
 - Default variants
 - Compound variants (combinations of multiple variant states)
+- Forwarding variant values via `forwardProps`
 - Polymorphic components with "as" prop
+- Optional `defaultProps` with strong typing (defaulted props become optional while respecting polymorphic `as`)
 - Custom class name combination strategies
 
 ## File Structure
@@ -58,7 +60,9 @@ src/
     }
   },
   defaultVariants?: {...},          // Default values
+  defaultProps?: {...},             // Defaulted non-variant props (e.g. { type: "button" })
   compoundVariants?: [...]          // Conditional class combinations
+  forwardProps?: ["disabled", ...]  // Variant keys to pass through as real props
 }
 ```
 
@@ -67,7 +71,9 @@ The library uses advanced TypeScript features to:
 - Infer variant prop types from configuration
 - Make variants required unless they have defaults or are boolean
 - Convert "true"/"false" keys to boolean props
+- Infer optionality for props supplied via `defaultProps` while preserving `as` polymorphism
 - Provide full autocomplete and type checking
+- Preserve variant prop ergonomics when using `forwardProps`; forwarded keys remain strongly typed and emitted alongside the generated className
 
 ## Usage Examples
 
@@ -99,6 +105,40 @@ const Card = styled("div", "bg-white p-4 border-2 rounded-lg");
 const CustomCard = styled(CustomComponent, "bg-white p-4 border-2 rounded-lg");
 ```
 
+### Default Props in Styled Components
+Provide defaults for non-variant props while keeping TypeScript happy:
+
+```tsx
+const Button = styled("button", {
+  base: "inline-flex items-center gap-2",
+  defaultProps: {
+    type: "button",
+  },
+});
+
+<Button />;             // `type` inferred as optional
+<Button type="submit" />; // Still overridable
+<Button as="a" href="/docs" />; // Works with polymorphic `as`
+```
+
+### Forwarding Variant Values
+Mirror a variant onto the rendered element to toggle native behaviour:
+
+```tsx
+const Button = styled("button", {
+  base: "inline-flex items-center gap-2",
+  variants: {
+    disabled: {
+      true: "opacity-50",
+    },
+  },
+  forwardProps: ["disabled"],
+});
+
+// Applies the class names *and* the DOM `disabled` prop
+<Button disabled />;
+```
+
 ### Polymorphic Components with "as" Prop
 Change the underlying element/component while keeping the same styles:
 
@@ -160,4 +200,4 @@ Add to VS Code settings.json:
 
 - Zero runtime dependencies
 - Development dependencies: React, Preact, TypeScript
-- Designed to work with any CSS framework (Tailwind, CSS modules, etc.)
+- Designed to work with any CSS framework (Tailwind, CSS modules, etc.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",
@@ -37,8 +37,11 @@
   },
   "scripts": {
     "build": "tsc",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write --unsafe .",
     "start": "npx vite",
-    "prepublishOnly": "npm run build"
+    "test": "vitest",
+    "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
     "tailwind",
@@ -49,11 +52,14 @@
     "preact"
   ],
   "devDependencies": {
+    "@biomejs/biome": "^2.2.6",
     "@types/react": "^18.0.26",
     "@types/react-dom": "^18.0.9",
+    "happy-dom": "^20.0.5",
     "preact": "^10.20.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "typescript": "^4.9.4"
+    "typescript": "^4.9.4",
+    "vitest": "^3.2.4"
   }
 }

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "happy-dom",
+    globals: true,
+    include: ["src/**/*.{test,spec}.{ts,tsx}"],
+  },
+});

package/.claude/settings.local.json

@@ -1,12 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run build:*)",
-      "Bash(npx tsc:*)",
-      "Bash(rm:*)",
-      "Bash(node:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}