npm package: @popgrids/ui
Description: A modern, production-ready React UI component library based on shadcn/ui principles, built with Base UI primitives and optimized for tree-shaking.
Author: PopGrids
Latest version: 0.0.38

# @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

```bash
pnpm add @popgrids/ui
```

Or with npm:

```bash
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.

```css
/* 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

```tsx
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

```tsx
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

```tsx
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:

```tsx
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:

```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:

```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:

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

## Tree-Shaking

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

```tsx
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:

```bash
pnpm changeset
```

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

Once you've created a changeset, run:

```bash
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:

```bash
git push origin main
```

And finally, publish the package:

```bash
pnpm changeset publish
```

This will publish the package to the npm registry.

## License

MIT