gd-ui-library

A comprehensive, production-ready React component library built natively — no external UI frameworks required. Fully typed with TypeScript.

✨ Features

• 70+ components covering every UI need
• Fully typed with TypeScript
• Zero external UI dependency — built from scratch
• Tailwind CSS powered styling
• Accessible — proper ARIA roles throughout
• Responsive — mobile-first design
• Works with React 18+ / Next.js (App Router)

📦 Installation

npm install gd-ui-library
# or
yarn add gd-ui-library
# or
pnpm add gd-ui-library

Import CSS

Add this once to your root layout or _app.tsx:

import 'gd-ui-library/dist/index.css';

🚀 Quick Start

"use client"; // Required in Next.js App Router

import { Button, Input, Alert, toast, Toaster } from "gd-ui-library";
import "gd-ui-library/dist/index.css";

export default function Page() {
  return (
    <div className="p-6 space-y-4">
      {/* Mount Toaster once in your layout */}
      <Toaster />

      <Alert variant="info" title="Welcome!" description="gd-ui-library is ready to use." />

      <Input label="Email" placeholder="[email protected]" />

      <Button variant="filled" onClick={() => toast.success("Hello!")}>
        Click me
      </Button>
    </div>
  );
}

Next.js App Router note: Because many components use React hooks and browser APIs, add "use client" at the top of any file that imports from gd-ui-library.

🧩 Component Categories

📝 Forms & Inputs

| Component | Description | |-----------|-------------| | Input | Text input with label, icons, error, and description | | Textarea | Multi-line input | | Select | Custom dropdown — single/multi, searchable | | Checkbox | Styled checkbox with label | | Radio | Radio button | | Toggle | On/off switch | | Slider | Range slider | | ColorPicker | Inline color picker | | Rating | Star rating | | OTPInput | One-time password digit boxes | | FileUpload | Drag-and-drop file upload | | DatePicker | Calendar date picker | | TimePicker | Time selection | | InputGroup | Input with prefix/suffix | | DebouncedInput | Input with debounce delay | | AutoComplete | Searchable dropdown, single or multi-select | | FormBuilder | Generate full forms from JSON | | ProductFilter | Sidebar filter panel with groups |

🖼️ Display

| Component | Description | |-----------|-------------| | Button | Button with variants, sizes, icons | | Badge | Small status label | | Chip | Removable tag with icon/avatar | | Avatar | Image or initials avatar with status dot | | Card + sub-components | Content container (CardHeader, CardTitle, CardDescription, CardContent, CardFooter) | | List / ListItem | Semantic list | | EmptyState | Placeholder for empty content areas | | Tooltip | Hover label | | Statistic | Animated number display | | ProgressBar | Horizontal progress indicator | | Skeleton | Loading placeholder |

🔔 Feedback & Status

| Component | Description | |-----------|-------------| | Alert | Inline notification banner | | toast / Toaster | Imperative toast notifications | | Spinner | Loading spinner | | Banner | Full-width announcement bar | | StatusIndicator | Colored dot with optional ping |

🧭 Navigation & Menus

| Component | Description | |-----------|-------------| | Navbar | Responsive top navigation bar | | Sidebar | Collapsible side navigation with nested items | | Breadcrumb | Page hierarchy trail | | Pagination | Page navigation with ellipsis | | Stepper | Multi-step progress indicator | | Dropdown | Standard / context / mega menu |

🔲 Overlays

| Component | Description | |-----------|-------------| | Dialog | Modal with overlay | | Drawer | Slide-in panel (any direction) | | Popover | Anchored floating panel |

🎛️ Interactive

| Component | Description | |-----------|-------------| | Accordion | Collapsible sections | | Tabs | Tabbed panels (solid/underline variants) | | Carousel | Slide show with controls and auto-play | | Timeline | Dated event list | | TreeView | Collapsible file/folder tree |

📐 Layout

| Component | Description | |-----------|-------------| | Grid | Responsive CSS grid (1–12 columns) | | Stack | FlexBox layout primitive | | SplitPane | Resizable two-panel layout | | MasonryGrid | Pinterest-style masonry columns | | Container | Centered max-width wrapper | | Section | Semantic <section> with padding | | Hero | Large hero banner area | | Footer | Semantic <footer> |

⚙️ Utilities & Behaviors

| Component | Description | |-----------|-------------| | Portal | Render children into document.body | | Transition | Mount/unmount CSS animations | | ClickAwayListener | Callback on outside click | | VirtualScroll | Virtualized list for 100K+ items | | InfiniteScroll | Load more on scroll | | LazyLoad | Defer rendering until in viewport |

📊 Advanced Widgets

| Component | Description | |-----------|-------------| | Table | Sortable, searchable, exportable data table | | Chart | SVG bar / line / pie / donut charts | | Calendar | Date-picker calendar | | CalendarWithEvents | Calendar with event markers | | GanttChart | Project timeline chart | | Kanban | Drag-and-drop Kanban board | | ShoppingCart | Cart UI with quantity controls and checkout | | RichTextEditor | WYSIWYG editor | | CodeEditor | Syntax-highlighted code editor | | FileManager | File browser with folder navigation | | EmailComposer | Email compose UI |

📖 Usage Examples

Input

import { Input } from "gd-ui-library";
import { Search } from "lucide-react";

<Input
  label="Search"
  placeholder="Type to search..."
  leftIcon={<Search className="w-4 h-4" />}
  description="Press Enter to search"
/>

<Input
  label="Password"
  type="password"
  error="Must be at least 8 characters"
/>

Select

import { Select } from "gd-ui-library";

const [role, setRole] = useState("");

<Select
  label="Role"
  value={role}
  onChange={setRole}
  searchable
  options={[
    { label: "Admin",  value: "admin"  },
    { label: "Editor", value: "editor" },
    { label: "User",   value: "user"   },
  ]}
/>

API Integration (Axios)

A full-featured API service for handling authentication, CSRF, and CRUD.

import { api, useQuery, useMutation, createResourceService } from "gd-ui-library";

// 1. Configure once
api.getCsrfToken(); // For Laravel Sanctum

// 2. Standard Query
const { data, loading } = useQuery("/users");

// 3. Mutation
const { mutate } = useMutation("post", "/login", {
  onSuccess: (res) => api.setToken(res.token)
});

// 4. Resource factory
const userService = createResourceService<User>("/users");
const users = await userService.getAll();

import { Table } from "gd-ui-library";

interface User { id: number; name: string; email: string; }

<Table<User>
  data={users}
  columns={[
    { key: "name",  header: "Name",  sortable: true, searchable: true },
    { key: "email", header: "Email", sortable: true },
  ]}
  onEdit={(u)   => handleEdit(u)}
  onDelete={(u) => handleDelete(u)}
  exportFileName="users"
/>

Toast

import { toast, Toaster } from "gd-ui-library";

// 1. Mount once in your root layout
<Toaster />

// 2. Call anywhere
toast.success("Saved!");
toast.error("Something went wrong.");
toast.warning("Please review your input.");
toast.info("New update available.");
toast({ title: "Custom", description: "With description", variant: "info", duration: 5000 });

Kanban

import { Kanban } from "gd-ui-library";

const columns = [
  { id: "todo", title: "To Do"        },
  { id: "wip",  title: "In Progress"  },
  { id: "done", title: "Done"         },
];

const [items, setItems] = useState([
  { id: "1", title: "Design UI",   columnId: "todo" },
  { id: "2", title: "Build API",   columnId: "wip"  },
  { id: "3", title: "Write tests", columnId: "done" },
]);

<Kanban columns={columns} items={items} onChange={setItems} />

Chart

import { Chart } from "gd-ui-library";

<Chart
  type="bar"
  labels={["Jan", "Feb", "Mar", "Apr", "May"]}
  datasets={[
    { label: "Revenue",  data: [4000, 5500, 4800, 7200, 6100], color: "#3B82F6" },
    { label: "Expenses", data: [2800, 3200, 3100, 4000, 3800], color: "#F59E0B" },
  ]}
  height={300}
/>

Dialog

import { Dialog, Button } from "gd-ui-library";

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>Open</Button>

<Dialog
  open={open}
  onOpenChange={setOpen}
  title="Confirm Delete"
  description="This action cannot be undone."
  footer={
    <>
      <Button onClick={() => setOpen(false)}>Cancel</Button>
      <Button variant="filled" onClick={handleDelete}>Delete</Button>
    </>
  }
>
  <p>Are you sure?</p>
</Dialog>

🗂️ Complete Import Reference

import {
  cn,

  // Forms
  Input, Textarea, Select, Checkbox, Radio, Toggle, Slider, ColorPicker,
  Rating, OTPInput, FileUpload, DatePicker, TimePicker, InputGroup,
  DebouncedInput, AutoComplete, FormBuilder, ProductFilter,

  // Button & Table
  Button, Table,

  // Display
  Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter,
  List, ListItem, Avatar, Badge, Chip, EmptyState, Tooltip,
  Statistic, ProgressBar, Skeleton,

  // Overlays
  Popover, Dialog, Drawer,

  // Feedback
  Alert, toast, Toaster, Spinner, Banner, StatusIndicator,

  // Navigation
  Navbar, Sidebar, Breadcrumb, Pagination, Stepper, Dropdown,

  // Interactive
  Accordion, Tabs, Carousel, Timeline, TreeView, Calendar, Kanban,

  // Layout
  Grid, Stack, SplitPane, MasonryGrid, Container, Section, Hero, Footer,

  // Utilities
  Portal, Transition, ClickAwayListener, VirtualScroll, InfiniteScroll, LazyLoad,

  // Widgets
  Chart, ShoppingCart, RichTextEditor, CodeEditor,
  FileManager, EmailComposer, CalendarWithEvents, GanttChart,
} from "gd-ui-library";

import "gd-ui-library/dist/index.css";

🛠️ Development

# Clone the repo
git clone <repo-url>
cd gd-ui-library

# Install dependencies
npm install

# Build the library
npm run build

Output

| File | Format | |------|--------| | dist/index.js | CommonJS | | dist/index.mjs | ES Module | | dist/index.d.ts | TypeScript types | | dist/index.css | Compiled styles |

📋 Peer Dependencies

| Package | Version | |---------|---------| | react | ^18.0.0 or ^19.0.0 | | react-dom | ^18.0.0 or ^19.0.0 |

🗒️ Changelog

v1.0.21

• Added GanttChart, EmailComposer, FileManager
• Added layout components: Grid, Stack, SplitPane, MasonryGrid, Container, Section, Hero, Footer
• Added utilities: Portal, Transition, ClickAwayListener, VirtualScroll, InfiniteScroll, LazyLoad
• Full TypeScript types for all new components

📄 License

ISC © gd-ui-library