Brutx

A Neo-Brutalism styled React UI component library

Bold. Raw. Unapologetic.

Component Library (brutx-ui)

CLI Tool (brutx)

Project Health & Sponsors

Documentation · NPM Library · NPM CLI · Report Bug

---

Brutx is a modern, neo-brutalist inspired React UI library. It implements bold 3px borders, thick black shadows, and high-contrast color palettes to give your application a raw, premium, and distinct character.

Instead of bloated npm dependencies, Brutx distributes components on-demand via a dynamic registry system (similar to shadcn/ui). You copy, paste, and customize the code directly in your workspace.

---

✨ Features

• 🎨 Neo-Brutalism Design: Thick 3px borders, high-contrast flat shadows, and vibrant accent colors.
• 🧱 27 Production-Ready Components: A fully realized component kit utilizing Radix UI primitives.
• 🌓 Dark Mode Native: Complete light & dark mode support with automatic dark border and shadow adjustments.
• ⚡ Dynamic Registry-Based CLI: Install components on-demand. Resolves and downloads dependency files recursively.
• 🚀 Tailwind CSS v3 & v4 Native: Native CSS utilities that integrate with JS configurations (v3) and CSS-first configurations (v4).
• 📱 Fully Accessible & Responsive: Compliant with WAI-ARIA standards and mobile-first responsive guidelines.
• 📦 Multi-Package Manager Detection: Detects and uses npm, pnpm, yarn, or bun automatically based on your project's lockfiles.

---

📦 Installation

Use the CLI brutx to initialize Brutx and add components to your project:

# Initialize Brutx configuration
npx brutx@latest init

# Add specific components
npx brutx@latest add button card badge

# Or add all 27 components at once
npx brutx@latest add --all

---

🚀 Quick Start

1. Initialize Project

Run the initialization wizard in your project root:

npx brutx@latest init

This will automatically:

• Detect your project type (Next.js, Vite, Remix, Create React App).
• Auto-detect the package manager (npm, pnpm, yarn, bun).
• Detect your Tailwind CSS version (v3 or v4).
• Create a components.json configuration file.
• Generate utility helpers (e.g., lib/utils.ts with the class merger helper cn).
• Append custom neo-brutalist utility classes directly to your global CSS stylesheet.
• Install core base dependencies (clsx, tailwind-merge, class-variance-authority, lucide-react).

2. Add Components

Add components individually or all at once:

# Add a single component (e.g., button)
npx brutx@latest add button

# Add multiple components
npx brutx@latest add button card dialog

# Force overwrite existing component files
npx brutx@latest add button --overwrite

3. Use in Your Project

Once installed, import and use the components inside your codebase:

import { Button } from "@/components/ui/button";
import { Card, CardHeader, CardContent } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";

export default function App() {
  return (
    <Card>
      <CardHeader>
        <h2 className="text-xl font-bold">Brutx App</h2>
        <Badge variant="success">Active</Badge>
      </CardHeader>
      <CardContent>
        <p className="mb-4">Bold, raw, and beautiful design patterns.</p>
        <Button variant="primary" size="default">
          Get Started
        </Button>
      </CardContent>
    </Card>
  );
}

---

🎨 Custom CSS Utility Classes

During initialization, Brutx appends native CSS custom classes directly to your project's global stylesheet. This guarantees 100% compatibility with both Tailwind CSS v3 and v4:

/* Brutx Styles */
.border-3 {
    border-width: 3px;
}

.shadow-brutal {
    box-shadow: 4px 4px 0px 0px #000;
}

.shadow-brutal-sm {
    box-shadow: 2px 2px 0px 0px #000;
}

.shadow-brutal-lg {
    box-shadow: 6px 6px 0px 0px #000;
}

/* Dark mode overrides */
.dark .shadow-brutal {
    box-shadow: 4px 4px 0px 0px #fff;
}
.dark .shadow-brutal-sm {
    box-shadow: 2px 2px 0px 0px #fff;
}
.dark .shadow-brutal-lg {
    box-shadow: 6px 6px 0px 0px #fff;
}

If you import components directly from the compiled npm library (brutx-ui), the following layer components are also available via styles.css:

• .nb-border - Apply a 3px solid black border.
• .nb-shadow - Apply a 4px black offset shadow.
• .nb-press - Apply a pressed interactive state effect.
• .nb-font - Apply a heavy 900 weight typography styling.

---

🧩 Supported Components (27 Core Components)

Brutx contains 27 core components grouped into 5 structural categories:

1. Layout & Containers

Component	Description	Local Install
Card	Nested container panels with headers, footers, and content boxes	npx brutx add card
Separator	Stylized horizontal or vertical separating lines	npx brutx add separator
ScrollArea	Custom scrollbar component with neo-brutalist rails	npx brutx add scroll-area

2. Forms & Inputs

Component	Description	Local Install
Button	High-contrast actions with loading indicators, sizes, and variants	npx brutx add button
SubmitButton	Server component-ready form submission handler	npx brutx add submit-button
Input	Text input boxes with rigid brutalist outlines	npx brutx add input
Textarea	High-contrast multi-line text input fields	npx brutx add textarea
Checkbox	Toggle checkmarks with offset borders	npx brutx add checkbox
Switch	Custom toggle switch wrapper based on Radix Switch	npx brutx add switch
Select	Dropdown picker with brutalist panels	npx brutx add select
Label	Rigid, accessible input labeling	npx brutx add label

3. Feedback & Status

Component	Description	Local Install
Alert	Standard status notifications (info, success, warning, error)	npx brutx add alert
Badge	High-contrast status pill indicators	npx brutx add badge
Toast	Fully managed snackbar notifications	npx brutx add toast
Spinner	Neo-brutalist loading animations (pulse, bars, rotate)	npx brutx add spinner
Skeleton	Content loading layout placeholders	npx brutx add skeleton

4. Overlays & Modals

Component	Description	Local Install
Dialog	Highly polished modal dialog windows	npx brutx add dialog
Popover	Contextual floating widgets	npx brutx add popover
Tooltip	Hover informational helpers	npx brutx add tooltip
DropdownMenu	Floating action trigger list	npx brutx add dropdown-menu

5. Navigation & Complex UI

Component	Description	Local Install
Tabs	Tab-switched panel navigation	npx brutx add tabs
Table	High-contrast structured data grids	npx brutx add table
Pagination	Grid routing indicators	npx brutx add pagination
Avatar	User thumbnail indicators with text fallback	npx brutx add avatar
Calendar	Day-picker wrapper using react-day-picker	npx brutx add calendar
Command	CmdK-based spotlight search command hub	npx brutx add command
Combobox	Multiselect/autocomplete picker utilizing command hub	npx brutx add combobox

---

🏗️ Project Monorepo Structure

brutx/
├── apps/
│   └── docs/                  # Next.js 15 documentation website
├── packages/
│   ├── ui/                    # Core NPM source library (brutx-ui)
│   │   ├── src/
│   │   │   ├── components/    # Component sources
│   │   │   └── styles.css     # UI library base stylesheet
│   │   └── package.json
│   ├── cli/                   # Dynamic CLI application (brutx)
│   │   ├── src/               # Commands CLI (`init`, `add`)
│   │   └── package.json
│   └── registry/              # Dynamically served Component Registry
│       ├── registry/          # Packaged components under JSON schemas
│       └── scripts/           # Build script to generate registry schemas
├── package.json
├── pnpm-workspace.yaml
└── README.md

---

🛠️ Development & Contributing Guide

To test CLI commands or components in a local environment:

1. Project Initialization & Setup

# Clone the repository
git clone https://github.com/dev-snake/brutxui.git
cd brutxui

# Install workspaces dependencies
pnpm install

# Build the UI library and CLI package
pnpm --filter brutx-ui build && pnpm --filter brutx build

2. Testing Locally

Run component test suites across the monorepo:

pnpm test

3. Registry Compilation

To package your modifications in packages/ui into the CLI registry:

pnpm --filter brutx-registry build

---

💖 Support This Project

If you find Brutx useful, please consider supporting its development:

Your support helps keep this project alive and growing! 🚀

---

📄 License

Brutx is open-source software licensed under the MIT License.

---

Made with 💛 and bold borders

NPM Library • NPM CLI • GitHub • Docs