classname-variants 1.6.0 → 1.7.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Felix Gnass
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -12,7 +12,28 @@ Library to create type-safe components that render their class name based on a s
 
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/classname-variants)
 
-# Examples
+## Installation
+
+```bash
+npm install classname-variants
+```
+
+## Import Paths
+
+```ts
+// Core — vanilla DOM, no framework dependency
+import { variants, classNames, tw } from "classname-variants";
+
+// React — styled components, variantProps, type utilities
+import { styled, variantProps, tw } from "classname-variants/react";
+import type { VariantPropsOf } from "classname-variants/react";
+
+// Preact — same API, accepts both `class` and `className`
+import { styled, variantProps, tw } from "classname-variants/preact";
+import type { VariantPropsOf } from "classname-variants/preact";
+```
+
+## Examples
 
 Here is an example that uses React and Tailwind CSS:
 
@@ -36,11 +57,9 @@ function UsageExample() {
 }
 ```
 
-[![Edit classname-variants/react](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/classname-variants-react-3bzjl?fontsize=14&hidenavigation=1&theme=dark)
-
 While the library has been designed with tools like Tailwind in mind, it can be also used with custom classes or CSS modules:
 
-## Preact + CSS modules
+### Preact + CSS modules
 
 ```tsx
 import { styled } from "classname-variants/preact";
@@ -56,7 +75,7 @@ const Button = styled("button", {
 });
 ```
 
-## Vanilla DOM
+### Vanilla DOM
 
 The core of the library is completely framework-agnostic:
 
@@ -80,7 +99,7 @@ document.write(`
 `);
 ```
 
-# API
+## API
 
 ### Defining variants
 
@@ -121,6 +140,8 @@ Variants can be typed as `boolean` by using `true` / `false` as key:
 <Button primary>Click Me!</Button>
 ```
 
+### Compound variants
+
 The `compoundVariants` option can be used to apply class names based on a combination of other variants:
 
 ```ts
@@ -188,6 +209,114 @@ 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 />;
+```
+
+### Chaining additional class names
+
+Styled components accept a `className` prop that gets merged with the variant output. This is useful for one-off overrides:
+
+```tsx
+<Button className="mt-4" size="large">Submit</Button>
+```
+
+The Preact adapter accepts both `class` and `className` — use whichever you prefer:
+
+```tsx
+<Button class="mt-4" size="large">Submit</Button>
+```
+
+### Ref forwarding
+
+All `styled()` components support refs via `React.forwardRef`:
+
+```tsx
+const Input = styled("input", {
+  base: "border rounded px-2",
+  variants: { ... },
+});
+
+const ref = useRef<HTMLInputElement>(null);
+<Input ref={ref} />;
+```
+
+### `variantProps()`
+
+The lower-level `variantProps()` function lets you separate variant logic from rendering. This is useful for headless components or when you need more control:
+
+```tsx
+import { variantProps } from "classname-variants/react";
+
+const buttonProps = variantProps({
+  base: "rounded px-4 py-2",
+  variants: {
+    intent: {
+      primary: "bg-teal-500 text-white",
+      secondary: "bg-slate-200",
+    },
+  },
+});
+
+function Button(props) {
+  // Extracts variant props, returns { className, ...rest }
+  const { className, ...rest } = buttonProps(props);
+  return <button className={className} {...rest} />;
+}
+```
+
+### `VariantPropsOf<T>`
+
+Use this utility type to extract the variant props accepted by a `variantProps` function — helpful when building wrapper components:
+
+```tsx
+import { variantProps, type VariantPropsOf } from "classname-variants/react";
+
+const buttonProps = variantProps({ ... });
+
+type ButtonProps = VariantPropsOf<typeof buttonProps>;
+// { intent: "primary" | "secondary"; className?: string }
+```
+
 ### 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).
@@ -250,7 +379,24 @@ import { twMerge } from "tailwind-merge";
 classNames.combine = twMerge;
 ```
 
-# Tailwind IntelliSense
+## Why classname-variants?
+
+### vs clsx / classnames
+
+- **Type safety** — full TypeScript inference for variant props instead of manual conditional logic
+- **Variant system** — built-in support for default values, compound variants, and boolean variants
+- **Framework bindings** — `styled()` creates ready-to-use React/Preact components
+
+### vs class-variance-authority (cva)
+
+- **Zero dependencies** — no external runtime dependencies
+- **Framework integration** — built-in `styled()` API with polymorphic `as` prop, ref forwarding, and `defaultProps`
+- **Prop forwarding** — `forwardProps` maps variant values to DOM attributes (e.g. `disabled`)
+- **TypeScript-first** — designed around type inference rather than requiring manual `VariantProps` extraction
+
+If you're coming from cva: `cva()` maps to `variants()`, and `VariantProps<typeof x>` maps to `VariantPropsOf<typeof x>`.
+
+## 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.
 
@@ -270,21 +416,17 @@ 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).
 
 In order to get type coverage even for your Tailwind classes, you can use a tool like [tailwind-ts](https://github.com/mathieutu/tailwind-ts).
 
-# For AI Assistants
+## For AI Assistants
 
 For comprehensive technical documentation optimized for LLMs, see [`llms.txt`](./llms.txt).
 
-# License
+## License
 
 MIT

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,17 +15,28 @@ 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 `class` prop) with equivalent `defaultProps` support
+
+### Class Application Order
+When generating class names, the library combines them in this order:
+1. `base` classes (always applied)
+2. Variant classes (based on selected or default variant values)
+3. Compound variant classes (when all conditions match)
+4. User-supplied `className` prop (React/Preact only, via chaining)
 
 ### Key Features
 - Type-safe variant definitions with full TypeScript inference
 - Support for required and optional variants
 - Boolean variants (true/false)
-- Default variants
+- Default variants via `defaultVariants` (note: NOT "defaults")
 - Compound variants (combinations of multiple variant states)
+- Forwarding variant values via `forwardProps`
 - Polymorphic components with "as" prop
-- Custom class name combination strategies
+- Optional `defaultProps` with strong typing (defaulted props become optional while respecting polymorphic `as`)
+- `className` prop chaining on styled components (user classes merged with variant output)
+- Ref forwarding — all `styled()` components use `forwardRef` internally
+- Works with any CSS framework (Tailwind, CSS modules, etc.) without additional dependencies
 
 ## File Structure
 
@@ -57,8 +68,10 @@ src/
       [optionName]: "class-names"
     }
   },
-  defaultVariants?: {...},          // Default values
+  defaultVariants?: {...},          // IMPORTANT: Use "defaultVariants" for default variant values
+  defaultProps?: {...},             // DIFFERENT: Use "defaultProps" for non-variant props (e.g. { type: "button" })
   compoundVariants?: [...]          // Conditional class combinations
+  forwardProps?: ["disabled", ...]  // Variant keys to pass through as real props
 }
 ```
 
@@ -67,7 +80,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
 
@@ -86,9 +101,9 @@ import { styled, tw } from "classname-variants/react"
 // Preact  
 import { styled, tw } from "classname-variants/preact"
 
-// Low-level API (rarely used directly)
-import { variantProps } from "classname-variants/react"
-import { variantProps } from "classname-variants/preact"
+// Low-level API and type utilities
+import { variantProps, type VariantPropsOf } from "classname-variants/react"
+import { variantProps, type VariantPropsOf } from "classname-variants/preact"
 ```
 
 ### Styled Components Without Variants
@@ -99,6 +114,78 @@ 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 />;
+```
+
+### className Prop Chaining
+Styled components accept an additional `className` prop that gets merged with the variant output:
+
+```tsx
+<Button className="mt-4" size="large">Submit</Button>
+```
+
+The Preact adapter accepts both `class` and `className` — they are merged together, so either works:
+
+```tsx
+<Button class="mt-4" size="large">Submit</Button>
+```
+
+### variantProps() for Headless Components
+The lower-level `variantProps()` function separates variant logic from rendering, useful for headless components or custom wrappers:
+
+```tsx
+import { variantProps, type VariantPropsOf } from "classname-variants/react";
+
+const buttonProps = variantProps({
+  base: "rounded px-4 py-2",
+  variants: {
+    intent: {
+      primary: "bg-teal-500 text-white",
+      secondary: "bg-slate-200",
+    },
+  },
+});
+
+// Extract the variant prop types for the wrapper component
+type ButtonProps = VariantPropsOf<typeof buttonProps>;
+
+function Button(props: ButtonProps) {
+  const { className, ...rest } = buttonProps(props);
+  return <button className={className} {...rest} />;
+}
+```
+
 ### Polymorphic Components with "as" Prop
 Change the underlying element/component while keeping the same styles:
 
@@ -113,8 +200,13 @@ const Button = styled("button", { variants: {...} });
 
 ### Tailwind CSS Integration
 
-#### Using tailwind-merge for Conflict Resolution
+The library works with Tailwind CSS out of the box without any additional dependencies.
+
+#### OPTIONAL: Using tailwind-merge for Class Conflict Resolution
+**This is completely optional.** Only consider using tailwind-merge if you need to resolve conflicting Tailwind classes (e.g., when allowing className overrides). Most use cases don't need this - design your variants to avoid conflicts instead to reduce complexity and overhead.
+
 ```ts
+// Only if you really need class merging:
 import { classNames } from "classname-variants";
 import { twMerge } from "tailwind-merge";
 
@@ -160,4 +252,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.1",
   "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 && vitest --run"
   },
   "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": []
-  }
-}