Getting Started

This guide will help you get started with styled-cva.

Installation

Install styled-cva using your preferred package manager:

npm

bash npm i --save @styled-cva/react

pnpm

bash pnpm add @styled-cva/react

bun

bash bun add @styled-cva/react

Basic Usage

Create a styled component using template literals:


import tw from "@styled-cva/react";
 
const StaticButton = tw.button`
  bg-primary rounded-xl cursor-pointer
`;
 
// Use it like a regular React component
<StaticButton>Click Me</StaticButton>;

Variants

Use the .cva() method to create components with variants:


import tw from "@styled-cva/react";
 
const VariantButton = tw.button.cva("btn-base-class", {
  variants: {
    // Variant keys starting with $ will not be sent to the DOM,
    // this avoids extraneous props warning
    $variant: {
      primary: "btn-primary-class",
      secondary: "btn-secondary-class",
    },
  },
});
 
// $variant is inferred to 'primary' | 'secondary'
<VariantButton $variant="primary">Click Me</VariantButton>;
 
// The actual element in the DOM will be:
// <button class="btn-primary-class">Click Me</button>

💡

Variant keys starting with $ are transient props that won’t be passed to the DOM element. This prevents React warnings about unknown props.

Default Props

Use .withProps() to set default props:


const StyledButton = tw.button
  .cva("btn-base", {
    variants: {
      $variant: {
        primary: "btn-primary",
        secondary: "btn-secondary",
      },
    },
  })
  .withProps({
    "data-testid": "my-button",
    type: "button",
    $variant: "primary", // Valid variant value
  });
 
// The component now has default props applied
<StyledButton>Click Me</StyledButton>;
 
// User props override defaults
<StyledButton $variant="secondary" type="submit">
  Submit
</StyledButton>;

Polymorphic Components

Use the $as prop to render as different elements or components:


import Link from "next/link";
 
const Button = tw.button.cva("btn", {
  variants: {
    $variant: {
      primary: "btn-primary",
      secondary: "btn-secondary",
    },
  },
});
 
// Works with known JSX elements
<Button $as="a" href="/some/url">
  I'm a link that looks like a button
</Button>;
 
// Also with custom components
<Button $as={Link} href="/some/url">
  I'm a link that looks like a button
</Button>;

Styling Custom Components

Create a styled component from a custom component that accepts a className prop:


import tw from "@styled-cva/react";
 
const MyButton = ({ className }: { className: string }) => {
  return <button className={className}>Hello</button>;
};
 
const StyledButton = tw(MyButton)`text-red-500`;
 
// Use it like a regular component
<StyledButton />;

VSCode IntelliSense

For Tailwind CSS extension support, add this to your VSCode settings.json:


{
  // tailwindcss intellisense settings
  "tailwindCSS.emmetCompletions": true,
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  },
  "tailwindCSS.experimental.classRegex": [
    "tw`([^`]*)",
    "tw\\.[^`]+`([^`]*)`",
    "tw\\(.*?\\).*?`([^`]*)",
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],
  "editor.quickSuggestions": {
    "strings": true
  }
}

💡

These settings enable Tailwind CSS IntelliSense for styled-cva template literals and CVA variant definitions.