Docs/Installation

Getting Started

Installation

Choose Native Beta or Shadcn Stable once during initialization. The CLI remembers that choice and automatically reuses it for every add command.

Introduction

Binhlaig UI is a collection of reusable React components designed for Next.js and Tailwind CSS projects.

Components are copied into your project

Binhlaig UI does not install components as a hidden dependency. Component source files are copied into your project, allowing you to customize the code and design.

Requirements

Make sure your development environment meets these requirements before installing Binhlaig UI.

Node.js

Node.js 20 or newer is required by the CLI.

Next.js

A Next.js App Router project with TypeScript is recommended.

Tailwind CSS

Tailwind CSS v4; Native init adds the required theme styles automatically.

Terminal

node --version
npm --version

Create a Next.js Project

Create a new Next.js project or continue with an existing project.

Create the project

Run the following command and select TypeScript, Tailwind CSS, App Router and the @/* import alias.

Terminal

npx create-next-app@latest my-app
cd my-app

Existing Next.js project

You can skip this section when your Next.js project already has TypeScript and Tailwind CSS configured.

Initialize Binhlaig UI

Choose an installer once. Binhlaig UI saves it in binhlaig.json for future add commands.

Run the init command

Run this command from the root of your Next.js project. The CLI first asks which installer you want to use.

Terminal

npx binhlaig-ui@latest init

Binhlaig Native Beta

Creates binhlaig.json, utility files, the UI directory, theme CSS, and required shared dependencies. The selected installer is saved automatically.

Terminal

npx binhlaig-ui@latest init --installer native

Shadcn CLI Stable

Uses the Shadcn initialization flow and saves "installer": "shadcn" in binhlaig.json for later add commands.

Terminal

npx binhlaig-ui@latest init --installer shadcn

binhlaig.json · Nativejson

{
  "$schema": "https://ui.binhlaig.com/schema.json",
  "installer": "native"
}

binhlaig.json · Shadcnjson

{
  "$schema": "https://ui.binhlaig.com/schema.json",
  "installer": "shadcn",
  "base": "base"
}

Optional: initialize non-interactively

Automation and CI workflows can explicitly select Native and skip confirmation prompts.

Terminal

npx binhlaig-ui@latest init --installer native --yes

Initialization completed

Initialization stores the selected installer in binhlaig.json. Future add commands automatically reuse Native or Shadcn unless --installer is passed as a one-command override.

Add Components

Install only the Binhlaig UI components required by your project.

Install your first component

Add the Button component. The CLI reads the installer saved during initialization, so no installer option is required.

Terminal

npx binhlaig-ui@latest add button

Installer selection is remembered

Native and Shadcn projects use the same add command. Pass--installeronly for a one-command override.

Install more components

You can install multiple components with one command. The saved installer is applied to every component.

Terminal

npx binhlaig-ui@latest add button card input badge tabs alert avatar breadcrumb

Import Components

Import installed components from the components/ui directory.

Button example

After installation, import and use the Button component.

app/page.tsxtsx

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

export default function Page() {
  return (
    <main className="p-10">
      <Button>
        Get Started
      </Button>
    </main>
  );
}

Card example

Components can be combined to build complete interface sections.

app/page.tsxtsx

import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

export default function Page() {
  return (
    <main className="flex min-h-screen items-center justify-center p-6">
      <Card className="w-full max-w-md">
        <CardHeader>
          <CardTitle>Binhlaig UI</CardTitle>

          <CardDescription>
            Reusable components for React and Next.js.
          </CardDescription>
        </CardHeader>

        <CardContent>
          Build modern interfaces quickly.
        </CardContent>

        <CardFooter>
          <Button className="w-full">
            Get Started
          </Button>
        </CardFooter>
      </Card>
    </main>
  );
}

Test the application

Start the development server and open your app.

Terminal

npm run dev

Dark Mode

Binhlaig UI components include dark mode styles using Tailwind CSS dark classes.

Install next-themes

Use next-themes to switch between light, dark and system themes.

Terminal

npm install next-themes

Create the Theme Provider

components/theme-provider.tsxtsx

"use client";

import * as React from "react";
import { ThemeProvider as NextThemesProvider } from "next-themes";

type ThemeProviderProps = React.ComponentProps<
  typeof NextThemesProvider
>;

export function ThemeProvider({
  children,
  ...props
}: ThemeProviderProps) {
  return (
    <NextThemesProvider {...props}>
      {children}
    </NextThemesProvider>
  );
}

Add the provider to the root layout

app/layout.tsxtsx

import type { Metadata } from "next";
import "./globals.css";

import { ThemeProvider } from "@/components/theme-provider";

export const metadata: Metadata = {
  title: "Binhlaig UI App",
  description: "Built with Binhlaig UI",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Project Structure

Installed components and configuration files are stored directly inside your project.

components/ui

Installed component source files.

lib/utils.ts

Utility functions such as cn().

binhlaig.json

Saved installer selection, component paths, aliases, and project configuration.

Project structure

my-app/
├── app/
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── theme-provider.tsx
│   └── ui/
│       ├── button.tsx
│       ├── card.tsx
│       └── input.tsx
├── lib/
│   └── utils.ts
├── binhlaig.json
├── package.json
└── tsconfig.json

Update or Overwrite a Component

Reinstall a component when a newer registry version is available.

Your existing file will be replaced

The overwrite option replaces the current component file. Save any custom changes before running this command.

Terminal

npx binhlaig-ui@latest add button --overwrite

Available Components

Use the list command to display components currently available in the Binhlaig UI registry.

Terminal

npx binhlaig-ui@latest list

Troubleshooting

Common issues that can occur while installing Binhlaig UI.

Command not found

Make sure Node.js and npm are installed. Use the complete npx command instead of calling the package directly.

Terminal

npx binhlaig-ui@latest init

binhlaig.json is missing

Run the init command in the project root before installing a component.

Terminal

npx binhlaig-ui@latest init

Dependencies are not working

Remove node_modules and the package lock file, then reinstall dependencies.

Windows PowerShell

Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install
npm run dev

macOS / Linux

rm -rf node_modules package-lock.json
npm install
npm run dev

Unknown component error

Check that the component exists in the current Binhlaig UI registry.

Terminal

npx binhlaig-ui@latest list

Home

Components