panda-css

a lightweight css utility helper library

weekly downloads7

versionv1.0.0

licenseISC

categorystyling

cssscsssassutility

Overview

panda-css is a build-time CSS-in-JS engine that uses static analysis to extract styles from your JavaScript or TypeScript code and generate optimized atomic CSS. Unlike traditional CSS-in-JS libraries that inject styles at runtime, Panda analyzes your code during the build process, produces static CSS files, and generates type-safe utility functions. This approach eliminates runtime performance costs while maintaining the developer experience of writing styles in JavaScript.

The library works by scanning your source files for style declarations—whether through utility functions like css(), JSX style props, or component recipes—and extracting them into atomic CSS classes. It then generates TypeScript definitions that provide autocomplete and type checking for your design tokens, CSS properties, and custom utilities. The output is standard CSS files that can be served like any static asset, with minimal JavaScript for runtime class name generation.

Panda is designed for teams building design systems or applications where performance and type safety are priorities. It bridges the gap between utility-first frameworks like Tailwind and traditional CSS-in-JS solutions, offering the composability and type safety of the latter with the performance characteristics of the former. The configuration system supports design tokens, custom utilities, responsive breakpoints, and component variants, making it suitable for both small projects and large-scale applications.

The package integrates via CLI commands or PostCSS plugin, working seamlessly with modern bundlers like Vite, Webpack, and Next.js. Developers configure themes and utilities in panda.config.ts, run the Panda CLI to generate a styled-system directory, and import type-safe functions to author styles. The result is maintainable, performant styling with the developer experience of CSS-in-JS and the runtime profile of static CSS.

Quick Start

typescript

// panda.config.ts
import { defineConfig } from '@pandacss/dev';

export default defineConfig({
  preflight: true,
  include: ['./src/**/*.{js,jsx,ts,tsx}'],
  exclude: [],
  outdir: 'styled-system',
  theme: {
    extend: {
      tokens: {
        colors: {
          primary: { value: '#3b82f6' },
          secondary: { value: '#8b5cf6' }
        },
        spacing: {
          sm: { value: '0.5rem' },
          md: { value: '1rem' },
          lg: { value: '2rem' }
        }
      }
    }
  }
});

// After running: npx panda codegen
// src/Button.tsx
import { css } from '../styled-system/css';
import { cva } from '../styled-system/css';

const buttonStyles = cva({
  base: {
    px: 'md',
    py: 'sm',
    borderRadius: 'md',
    fontWeight: 'semibold',
    cursor: 'pointer',
    transition: 'all 0.2s'
  },
  variants: {
    variant: {
      primary: {
        bg: 'primary',
        color: 'white',
        _hover: { opacity: 0.9 }
      },
      secondary: {
        bg: 'secondary',
        color: 'white',
        _hover: { opacity: 0.9 }
      }
    },
    size: {
      sm: { fontSize: 'sm', px: 'sm' },
      md: { fontSize: 'md', px: 'md' },
      lg: { fontSize: 'lg', px: 'lg' }
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});

export function Button({ variant, size, children }) {
  return (
    <button className={buttonStyles({ variant, size })}>
      {children}
    </button>
  );
}

// src/Card.tsx
import { css } from '../styled-system/css';
import { stack } from '../styled-system/patterns';

export function Card({ title, description }) {
  return (
    <div className={css({
      p: 'lg',
      bg: 'white',
      borderRadius: 'lg',
      boxShadow: 'md',
      _hover: { boxShadow: 'lg' }
    })}>
      <div className={stack({ gap: 'sm' })}>
        <h3 className={css({ fontSize: 'xl', fontWeight: 'bold' })}>
          {title}
        </h3>
        <p className={css({ color: 'gray.600' })}>
          {description}
        </p>
      </div>
    </div>
  );
}

Use Cases

Design System Implementation: Teams building component libraries can define design tokens (colors, spacing, typography) in Panda's config and generate type-safe styling primitives. The generated TypeScript types ensure components only use approved design values, preventing inconsistencies across the codebase.

Server-Side Rendered Applications: Applications using Next.js App Router or similar SSR frameworks benefit from Panda's zero-runtime approach. Styles are extracted at build time and served as static CSS, eliminating the flash-of-unstyled-content issues and hydration overhead common with runtime CSS-in-JS.

Performance-Critical User Interfaces: Projects where bundle size and runtime performance matter—such as e-commerce sites or mobile web apps—can use Panda to write component-scoped styles without paying the cost of runtime style injection. The atomic CSS approach also enables aggressive caching and reuse.

Gradual Migration from Utility Frameworks: Codebases transitioning away from Tailwind or similar utility frameworks can adopt Panda to maintain utility-style authoring while gaining type safety and more semantic APIs. The css() function provides similar short-hand properties with better IDE support.

Multi-Framework Monorepos: Organizations with multiple frontend applications across different frameworks (React, Vue, Solid) can share a single Panda configuration and design system. The build-time extraction works framework-agnostically, generating portable CSS and minimal runtime helpers.

Pros & Cons

Pros

+Zero runtime overhead—all CSS is generated at build time, resulting in faster page loads and no JavaScript-based style injection
+Full TypeScript integration with auto-generated types for design tokens, utilities, and CSS properties, providing compile-time safety and excellent IDE autocomplete
+Atomic CSS output with modern features like cascade layers and CSS variables, enabling efficient caching and minimal duplication
+Framework-agnostic design works with any JavaScript framework or build tool via CLI or PostCSS integration
+Comprehensive configuration system supporting design tokens, custom utilities, component recipes, and responsive patterns without writing raw CSS

Cons

−Build-time extraction requires re-running the CLI or build process during development, adding a compilation step compared to plain CSS
−Dynamic styles based on runtime data require workarounds like CSS variables or pre-generating variants via staticCss configuration
−Smaller ecosystem and community compared to established solutions like Styled Components or Tailwind, with fewer third-party integrations and plugins
−Learning curve for developers unfamiliar with design token systems and the configuration-driven approach to styling
−Generated styled-system output directory must be committed or generated in CI/CD pipelines, adding repository overhead

Alternatives

styled-componentsv6.3.10

CSS for the <Component> Age. Style components your way with speed, strong typing, and flexibility.

stylingreactcss

7.8M / week

tailwindcssv4.2.0

A utility-first CSS framework for rapidly building custom user interfaces.

styling

44.0M / week

@vanilla-extract/cssv1.18.0

Zero-runtime Stylesheets-in-TypeScript

styling

1.3M / week

Comparisons

@vanilla-extract/css vs panda-css

styling

Install

bash

npm install panda-css

bash

pnpm add panda-css

bash

bun add panda-css

Overview

Quick Start

typescript

// panda.config.ts
import { defineConfig } from '@pandacss/dev';

export default defineConfig({
  preflight: true,
  include: ['./src/**/*.{js,jsx,ts,tsx}'],
  exclude: [],
  outdir: 'styled-system',
  theme: {
    extend: {
      tokens: {
        colors: {
          primary: { value: '#3b82f6' },
          secondary: { value: '#8b5cf6' }
        },
        spacing: {
          sm: { value: '0.5rem' },
          md: { value: '1rem' },
          lg: { value: '2rem' }
        }
      }
    }
  }
});

// After running: npx panda codegen
// src/Button.tsx
import { css } from '../styled-system/css';
import { cva } from '../styled-system/css';

const buttonStyles = cva({
  base: {
    px: 'md',
    py: 'sm',
    borderRadius: 'md',
    fontWeight: 'semibold',
    cursor: 'pointer',
    transition: 'all 0.2s'
  },
  variants: {
    variant: {
      primary: {
        bg: 'primary',
        color: 'white',
        _hover: { opacity: 0.9 }
      },
      secondary: {
        bg: 'secondary',
        color: 'white',
        _hover: { opacity: 0.9 }
      }
    },
    size: {
      sm: { fontSize: 'sm', px: 'sm' },
      md: { fontSize: 'md', px: 'md' },
      lg: { fontSize: 'lg', px: 'lg' }
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
});

export function Button({ variant, size, children }) {
  return (
    <button className={buttonStyles({ variant, size })}>
      {children}
    </button>
  );
}

// src/Card.tsx
import { css } from '../styled-system/css';
import { stack } from '../styled-system/patterns';

export function Card({ title, description }) {
  return (
    <div className={css({
      p: 'lg',
      bg: 'white',
      borderRadius: 'lg',
      boxShadow: 'md',
      _hover: { boxShadow: 'lg' }
    })}>
      <div className={stack({ gap: 'sm' })}>
        <h3 className={css({ fontSize: 'xl', fontWeight: 'bold' })}>
          {title}
        </h3>
        <p className={css({ color: 'gray.600' })}>
          {description}
        </p>
      </div>
    </div>
  );
}

Use Cases

Pros & Cons

Pros

+Zero runtime overhead—all CSS is generated at build time, resulting in faster page loads and no JavaScript-based style injection
+Full TypeScript integration with auto-generated types for design tokens, utilities, and CSS properties, providing compile-time safety and excellent IDE autocomplete
+Atomic CSS output with modern features like cascade layers and CSS variables, enabling efficient caching and minimal duplication
+Framework-agnostic design works with any JavaScript framework or build tool via CLI or PostCSS integration
+Comprehensive configuration system supporting design tokens, custom utilities, component recipes, and responsive patterns without writing raw CSS

Cons

−Build-time extraction requires re-running the CLI or build process during development, adding a compilation step compared to plain CSS
−Dynamic styles based on runtime data require workarounds like CSS variables or pre-generating variants via staticCss configuration
−Smaller ecosystem and community compared to established solutions like Styled Components or Tailwind, with fewer third-party integrations and plugins
−Learning curve for developers unfamiliar with design token systems and the configuration-driven approach to styling
−Generated styled-system output directory must be committed or generated in CI/CD pipelines, adding repository overhead