@popgrids/ui

A modern, production-ready React UI component library based on shadcn/ui principles, built with Radix UI primitives and optimized for tree-shaking.

Installation

pnpm add @popgrids/ui

Or with npm:

npm install @popgrids/ui

Peer Dependencies

This library requires the following peer dependencies:

• react ^18 or ^19
• react-dom ^18 or ^19.0.0
• radix-ui ^1.4.3
• tailwindcss ^4.0.0
• @untitledui/icons ^0.1.0
• @fontsource-variable/inter ^5.2.8
• @fontsource/poppins ^5.2.7

Optional peer dependencies:

• @tailwindcss/typography ^0.5.19

Requirements

• React 19+
• Tailwind CSS v4 configured in your project
• TypeScript (recommended)

Usage

Step 1: Import the Theme CSS

Import the library's theme CSS file in your main CSS file (not in JavaScript). This file includes theme variables and tells Tailwind to scan the library's component files.

/* Your main CSS file (e.g., app.css, index.css, globals.css) */
@import "tailwindcss";
/* Import the library's theme and source definitions */
@import "@popgrids/ui/theme.css";

Step 2: Import and Use Components

import { Button } from "@popgrids/ui/button";

function App() {
  return <Button>Click me</Button>;
}

That's it! The @import "@popgrids/ui/theme.css" line:

• Defines the library's theme variables
• Tells Tailwind to scan @popgrids/ui/dist/**/*.{js,cjs} for class names
• Automatically generates CSS for all classes used in the components

Variants

import { Button } from "@popgrids/ui/button";

function App() {
  return (
    <>
      <Button variant="default">Default</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="link">Link</Button>
    </>
  );
}

Sizes

import { Button } from "@popgrids/ui/button";

function App() {
  return (
    <>
      <Button size="xs">Extra Small</Button>
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
      <Button size="icon">Icon</Button>
    </>
  );
}

Using buttonVariants

You can also use the buttonVariants function directly for custom styling:

import { buttonVariants } from "@popgrids/ui";
import { cn } from "./lib/utils";

function CustomButton({ className, ...props }) {
  return (
    <button
      className={cn(buttonVariants({ variant: "outline", size: "lg" }), className)}
      {...props}
    />
  );
}

Theming

The library's theme is included when you import @popgrids/ui/theme.css. This file defines:

1. Theme variables using Tailwind v4's @theme directive
2. CSS variables for backward compatibility
3. Source directives that tell Tailwind to scan the library's component files

Default Theme

The theme CSS file includes default design tokens. You can customize them by overriding the variables in your own CSS:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 221.2 83.2% 53.3%;
  --radius: 0.5rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;
  --primary: 217.2 91.2% 59.8%;
  --primary-foreground: 222.2 47.4% 11.2%;
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 98%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 210 40% 98%;
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 224.3 76.3% 48%;
}

Customizing Theme Variables

You can customize any variable to match your design system. Simply override the values in your CSS:

:root {
  --primary: 221.2 83.2% 53.3%; /* Your primary color */
  --radius: 0.5rem; /* Your border radius */
  /* Customize other variables as needed */
}

Dark Mode

Apply the .dark class to your root element to enable dark mode:

<html className="dark">
  {/* Your app */}
</html>

Tree-Shaking

This library is fully tree-shakeable. When you import only the components you need:

import { Button } from "@popgrids/ui/button";

Your bundler will only include the Button component and its dependencies, not unused exports.

How It Works

When you import @popgrids/ui/theme.css in your main CSS file:

1. Theme variables are defined using Tailwind v4's @theme directive
2. CSS variables are set for backward compatibility (used in component classes like hsl(var(--primary)))
3. @source directive tells Tailwind to scan @popgrids/ui/dist/**/*.{js,cjs} for class names
4. Tailwind generates CSS for all classes found in the library's components
5. No manual configuration needed - the @source directive handles everything!

Requirements

• Tailwind CSS v4 (required for @theme and @source directives)
• Import @popgrids/ui/theme.css in your main CSS file (not in JavaScript)

TypeScript

Full TypeScript support is included. All components are typed and exported with their proper types.

Changesets

This library uses Changesets to manage versions. To create a new version, run:

pnpm changeset

This will open an interactive prompt to help you create a changeset.

Once you've created a changeset, run:

pnpm changeset version

This will update the version in the package.json file and create a new git tag.

Then push the changes to the repository:

git push origin main

And finally, publish the package:

pnpm changeset publish

This will publish the package to the npm registry.

License

MIT