classname-variants 1.2.1 → 1.3.0

package/README.md

@@ -4,13 +4,13 @@ Stitches-like [variant API](https://stitches.dev/docs/variants) for plain class
 
 The library is framework agnostic and can be used with any kind of CSS flavor.
 
-It is especially useful though if used with [Tailwind](https://tailwindcss.com/) or [CSS Modules](https://github.com/css-modules/css-modules) in cobmination with React, as it provides some [dedicated helpers](#React) and even allows for a _styled-components_ like API, but with [class names instead of styles](#bonus-styled-components-but-with-class-names-)!
+It is especially useful though if used with [Tailwind](https://tailwindcss.com/) or [CSS Modules](https://github.com/css-modules/css-modules) in combination with React, as it provides some [dedicated helpers](#React) and even allows for a _styled-components_ like API, but with [class names instead of styles](#bonus-styled-components-but-with-class-names-)!
 
 [![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)
 
 # Basics
 
-Let's aussume we want to build a button component with Tailwind CSS that comes in different sizes and colors.
+Let's assume we want to build a button component with Tailwind CSS that comes in different sizes and colors.
 
 It consists of some _base classes_ that are always present as well as some optional classes that need to be added depending on the desired _variants_.
 
@@ -135,10 +135,10 @@ const buttonProps = variantProps({
 });
 ```
 
-This way a compontents' props (or part of them) can be directly spread into the target element. All variant-related props are used to construct the `className` property while all other props are passed through verbatim:
+This way a component's props (or part of them) can be directly spread into the target element. All variant-related props are used to construct the `className` property while all other props are passed through verbatim:
 
 ```tsx
-type Props = SX.IntrinsicElements["button"] &
+type Props = JSX.IntrinsicElements["button"] &
   VariantPropsOf<typeof buttonProps>;
 
 function Button(props: Props) {
@@ -154,9 +154,9 @@ function App() {
 }
 ```
 
-# Bonus: styled-components, but with class names 💅
+# Bonus: styled-components, but for static CSS 💅
 
-Things can be taken even a step further, resulting in a _styled-components_ like way of defining reusable components:
+Things can be taken even a step further, resulting in a _styled-components_ like way of defining reusable components. Under the hood, this does basically the same as the example above, but also handles _refs_ correctly:
 
 ```tsx
 import { styled } from "classname-variants/react";
@@ -171,7 +171,7 @@ const Button = styled("button", {
 });
 ```
 
-The same can be done with CSS modules:
+Again, this is not limited to tailwind, so you could do the same with CSS modules:
 
 ```tsx
 import { styled } from "classname-variants/react";
@@ -187,7 +187,33 @@ const Button = styled("button", {
 });
 ```
 
-You can also style other custom React components as long as the accept a `className` prop.
+**NOTE:** You can also style other custom React components as long as they accept a `className` prop.
+
+## Polymorphic components with "as"
+
+If you want to keep all the variants you have defined for a component but want to render a different HTML tag or a different custom component, you can use the "as" prop to do so:
+
+```tsx
+import { styled } from "classname-variants/react";
+import styles from "./styles.module.css";
+
+const Button = styled("button", {
+  variants: {
+    //...
+  },
+});
+
+function App() {
+  return (
+    <div>
+      <Button>I'm a button</Button>
+      <Button as="a" href="/">
+        I'm a link!
+      </Button>
+    </div>
+  );
+}
+```
 
 # Tailwind IntelliSense
 

package/example.tsx

@@ -58,6 +58,9 @@ function App() {
         <h1>Hello</h1>
         <p>world</p>
       </Card>
+      <Card as="a" href="https://example.com">
+        Link
+      </Card>
     </div>
   );
 }

package/lib/react.d.ts

@@ -1,4 +1,4 @@
-import { ComponentProps, ElementType, ForwardRefExoticComponent, PropsWithoutRef } from "react";
+import { ComponentProps, ElementType, ReactElement } from "react";
 import { Variants, VariantsConfig, VariantOptions, Simplify } from "./index.js";
 /**
  * Utility type to infer the first argument of a variantProps function.
@@ -13,7 +13,18 @@ declare type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["v
 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"]>;
-declare type StyledComponent<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = C["variants"]> = ForwardRefExoticComponent<PropsWithoutRef<ComponentProps<T> & VariantOptions<C>> & React.RefAttributes<T>>;
 declare type VariantsOf<T> = T extends VariantsConfig<infer V> ? V : {};
-export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C>>(type: T, config: string | Simplify<C>): StyledComponent<T, C>;
+declare type AsProps<T extends ElementType = ElementType> = {
+    as?: T;
+};
+declare 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>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: AsProps<As> & Omit<ComponentProps<As>, "as"> & { [K in keyof C["variants"] as K extends keyof { [K_1 in keyof C["variants"] as C["variants"][K_1] extends {
+    true: any;
+} | {
+    false: any;
+} ? K_1 : never]: C["variants"][K_1]; } | keyof { [K_2 in keyof C["variants"] as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } ? never : K]: { [K_3 in keyof C["variants"]]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; }[K]; } & { [K_4 in keyof C["variants"] as K_4 extends keyof { [K_1 in keyof C["variants"] as C["variants"][K_1] extends {
+    true: any;
+} | {
+    false: any;
+} ? K_1 : never]: C["variants"][K_1]; } | keyof { [K_2 in keyof C["variants"] as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } ? K_4 : never]?: { [K_3 in keyof C["variants"]]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; }[K_4] | undefined; }) => ReactElement | null;
 export {};

package/lib/react.js

@@ -21,5 +21,8 @@ export function styled(type, config) {
     const styledProps = typeof config === "string"
         ? variantProps({ base: config, variants: {} })
         : variantProps(config);
-    return forwardRef((props, ref) => createElement(type, { ...styledProps(props), ref }));
+    const Component = forwardRef(({ as, ...props }, ref) => {
+        return createElement(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
+    });
+    return Component;
 }

package/package.json

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

package/src/react.ts

@@ -3,8 +3,8 @@ import {
   createElement,
   ElementType,
   forwardRef,
-  ForwardRefExoticComponent,
-  PropsWithoutRef,
+  ReactElement,
+  Ref,
 } from "react";
 
 import {
@@ -52,27 +52,31 @@ export function variantProps<
   };
 }
 
-type StyledComponent<
-  T extends ElementType,
-  C extends VariantsConfig<V>,
-  V extends Variants = C["variants"]
-> = ForwardRefExoticComponent<
-  PropsWithoutRef<ComponentProps<T> & VariantOptions<C>> &
-    React.RefAttributes<T>
->;
-
 type VariantsOf<T> = T extends VariantsConfig<infer V> ? V : {};
 
+type AsProps<T extends ElementType = ElementType> = {
+  as?: T;
+};
+
+type PolymorphicComponentProps<T extends ElementType> = AsProps<T> &
+  Omit<ComponentProps<T>, "as">;
+
 export function styled<
   T extends ElementType,
   C extends VariantsConfig<V>,
   V extends Variants = VariantsOf<C>
->(type: T, config: string | Simplify<C>): StyledComponent<T, C> {
+>(type: T, config: string | Simplify<C>) {
   const styledProps =
     typeof config === "string"
       ? variantProps({ base: config, variants: {} })
       : variantProps(config);
-  return forwardRef<T, ComponentProps<T> & VariantOptions<C>>((props, ref) =>
-    createElement(type, { ...styledProps(props), ref })
+
+  const Component: <As extends ElementType = T>(
+    props: PolymorphicComponentProps<As> & VariantOptions<C>
+  ) => ReactElement | null = forwardRef(
+    ({ as, ...props }: AsProps, ref: Ref<Element>) => {
+      return createElement(as ?? type, { ...styledProps(props), ref });
+    }
   );
+  return Component;
 }