Braid UI

A comprehensive React UI component library built with TypeScript, Tailwind CSS, and Radix UI primitives.

Installation

npm install braid-ui
# or
yarn add braid-ui
# or
pnpm add braid-ui

Quick Start

import { Button, Card } from 'braid-ui'
import 'braid-ui/styles'

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

Peer Dependencies

Braid UI requires the following peer dependencies. Make sure they are installed:

npm install react react-dom react-router-dom \
  @radix-ui/react-accordion @radix-ui/react-alert-dialog \
  @radix-ui/react-aspect-ratio @radix-ui/react-avatar \
  @radix-ui/react-checkbox @radix-ui/react-collapsible \
  @radix-ui/react-context-menu @radix-ui/react-dialog \
  @radix-ui/react-dropdown-menu @radix-ui/react-hover-card \
  @radix-ui/react-label @radix-ui/react-menubar \
  @radix-ui/react-navigation-menu @radix-ui/react-popover \
  @radix-ui/react-progress @radix-ui/react-radio-group \
  @radix-ui/react-scroll-area @radix-ui/react-select \
  @radix-ui/react-separator @radix-ui/react-slider \
  @radix-ui/react-slot @radix-ui/react-switch \
  @radix-ui/react-tabs @radix-ui/react-toast \
  @radix-ui/react-toggle @radix-ui/react-toggle-group \
  @radix-ui/react-tooltip \
  @tanstack/react-query @hookform/resolvers \
  class-variance-authority clsx cmdk date-fns \
  embla-carousel-react input-otp lucide-react next-themes \
  react-day-picker react-hook-form react-resizable-panels \
  recharts sonner tailwind-merge tailwindcss-animate vaul zod \
  lodash react-pdf

Or install them individually as needed. See the full list in package.json under peerDependencies.

Setup

1. Import Styles

Import the CSS styles in your application entry point:

// In your main.tsx, App.tsx, or index.tsx
import 'braid-ui/styles'

Alternatively, import in your main CSS file:

/* In your globals.css or main.css */
@import 'braid-ui/styles';

2. Configure Tailwind CSS

Braid UI requires Tailwind CSS to be configured in your project. Add the library's theme extensions to your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/braid-ui/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
          glow: 'hsl(var(--primary-glow))'
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))'
        },
        destructive: {
          DEFAULT: 'hsl(var(--destructive))',
          foreground: 'hsl(var(--destructive-foreground))'
        },
        success: {
          DEFAULT: 'hsl(var(--success))',
          foreground: 'hsl(var(--success-foreground))'
        },
        warning: {
          DEFAULT: 'hsl(var(--warning))',
          foreground: 'hsl(var(--warning-foreground))'
        },
        muted: {
          DEFAULT: 'hsl(var(--muted))',
          foreground: 'hsl(var(--muted-foreground))'
        },
        accent: {
          DEFAULT: 'hsl(var(--accent))',
          foreground: 'hsl(var(--accent-foreground))'
        },
        popover: {
          DEFAULT: 'hsl(var(--popover))',
          foreground: 'hsl(var(--popover-foreground))'
        },
        card: {
          DEFAULT: 'hsl(var(--card))',
          foreground: 'hsl(var(--card-foreground))'
        },
        form: {
          background: 'hsl(var(--form-background))',
          border: 'hsl(var(--form-border))',
          'border-focus': 'hsl(var(--form-border-focus))',
          'border-error': 'hsl(var(--form-border-error))',
          'border-success': 'hsl(var(--form-border-success))'
        },
        sidebar: {
          DEFAULT: 'hsl(var(--sidebar-background))',
          foreground: 'hsl(var(--sidebar-foreground))',
          primary: 'hsl(var(--sidebar-primary))',
          'primary-foreground': 'hsl(var(--sidebar-primary-foreground))',
          accent: 'hsl(var(--sidebar-accent))',
          'accent-foreground': 'hsl(var(--sidebar-accent-foreground))',
          border: 'hsl(var(--sidebar-border))',
          ring: 'hsl(var(--sidebar-ring))'
        }
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)'
      },
      keyframes: {
        'accordion-down': {
          from: { height: '0' },
          to: { height: 'var(--radix-accordion-content-height)' }
        },
        'accordion-up': {
          from: { height: 'var(--radix-accordion-content-height)' },
          to: { height: '0' }
        }
      },
      animation: {
        'accordion-down': 'accordion-down 0.2s ease-out',
        'accordion-up': 'accordion-up 0.2s ease-out'
      },
      backgroundImage: {
        'gradient-primary': 'var(--gradient-primary)',
        'gradient-subtle': 'var(--gradient-subtle)'
      },
      boxShadow: {
        'form': 'var(--shadow-form)',
        'form-focus': 'var(--shadow-form-focus)',
        'form-error': 'var(--shadow-form-error)'
      },
      transitionProperty: {
        'form': 'var(--transition-form)'
      }
    }
  },
  plugins: [require('tailwindcss-animate')],
}

Important: Make sure tailwindcss-animate is installed:

npm install -D tailwindcss-animate

Usage

Importing Components

Import components directly from the main package:

import { Button, Card, Dialog, Input } from 'braid-ui'

Using Components

import { Button, Card, CardHeader, CardTitle, CardContent } from 'braid-ui'

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Card Title</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  )
}

Using Hooks

import { useToast, useEditState } from 'braid-ui'

function MyComponent() {
  const { toast } = useToast()
  
  return (
    <button onClick={() => toast({ 
      title: 'Success!',
      description: 'Action completed successfully.'
    })}>
      Show Toast
    </button>
  )
}

Using Pages

import { Dashboard, Alerts, Businesses } from 'braid-ui'
import { BrowserRouter, Routes, Route } from 'react-router-dom'

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Dashboard />} />
        <Route path="/alerts" element={<Alerts />} />
        <Route path="/businesses" element={<Businesses />} />
      </Routes>
    </BrowserRouter>
  )
}

Styling Options

With Tailwind CSS (Recommended)

If you're using Tailwind CSS, import the styles and configure your Tailwind config as shown above.

Without Tailwind CSS

If you're not using Tailwind CSS, you can use the pre-compiled CSS:

// Import pre-compiled CSS
import 'braid-ui/css'
// or minified version
import 'braid-ui/css/min'

You can also import just the CSS variables:

import 'braid-ui/css/variables'

Customizing Colors

You can customize the color scheme by overriding CSS variables:

:root {
  --primary: 204 100% 54%;
  --primary-foreground: 0 0% 100%;
  --background: 240 10% 98%;
  --foreground: 240 10% 8%;
  /* ... override other variables as needed */
}

Note: Colors should be defined as HSL values without the hsl() wrapper.

Dark Mode

Braid UI supports dark mode automatically. The CSS variables switch when the .dark class is present on a parent element (usually <html> or <body>).

If you're using a theme provider like next-themes:

import { ThemeProvider } from 'next-themes'

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      {/* Your app */}
    </ThemeProvider>
  )
}

TypeScript

Braid UI is built with TypeScript and includes type definitions. No additional @types packages are required.

Next.js Configuration

If you're using Braid UI in a Next.js application and need to use components that include PDF viewing (like BusinessDetailView with BusinessDocuments), you'll need to configure Next.js webpack to handle react-pdf dependencies correctly.

Add the following to your next.config.js:

const nextConfig = {
  webpack: (config, { isServer }) => {
    // Fix for react-pdf/pdfjs-dist in Next.js
    if (!isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        canvas: false,
      }
    }
    return config
  },
}

module.exports = nextConfig

This prevents Next.js from trying to bundle Node.js-specific dependencies that pdfjs-dist might reference during webpack analysis.

Note: If you're not using any PDF-related components, this configuration is optional.

License

MIT

Repository

GitHub Repository