alope-ui 1.1.2 → 1.1.3

package/README.md

@@ -96,16 +96,23 @@ export default App;
 
 - [🪗 Accordion](#accordion) - Collapsible content panels
 - [🍞 Breadcrumb](#breadcrumb) - Navigation trail
+- [📑 Tabs](#tabs) - Tabbed navigation interface
+- [📄 Pagination](#pagination) - Page navigation controls
 
 ### Feedback Components
 
 - [⚠️ Alert](#alert) - Status messages and notifications
 - [🍞 Toast](#toast) - Temporary notification messages
+- [💡 Tooltip](#tooltip) - Contextual information on hover
+- [⏳ Spinner](#spinner) - Loading indicators
+- [💀 Skeleton](#skeleton) - Content loading placeholders
 
 ### Data Display
 
 - [🏷️ Badge](#badge) - Status indicators and labels
 - [🃏 Card](#card) - Content containers
+- [📊 Table](#table) - Tabular data display
+- [👤 Avatar](#avatar) - User profile images
 
 ### Form Controls
 
@@ -113,6 +120,9 @@ export default App;
 - [🔘 Radio Input](#radio-input) - Single choice selections
 - [📝 Select Input](#select-input) - Dropdown selections
 - [⌨️ Text Input](#text-input) - Text input fields
+- [📝 Textarea](#textarea) - Multi-line text input
+- [🔄 Toggle](#toggle) - Switch controls
+- [📁 File Upload](#file-upload) - File selection and upload
 
 ### Interactive Elements
 
@@ -1703,6 +1713,2388 @@ const BasicExample = () => {
 />
 ```
 
+---
+
+## Pagination
+
+The Pagination component provides navigation controls for paginated content, supporting both simplified and full pagination modes with customizable appearance.
+
+### Import
+
+```jsx
+import { Pagination } from "alope-ui";
+```
+
+### Props
+
+| Prop            | Type                              | Default   | Description                                           |
+| --------------- | --------------------------------- | --------- | ----------------------------------------------------- |
+| `currentPage`   | `number`                          | `required`| Current active page number                            |
+| `onPageChange`  | `(page: number) => void`          | `required`| Callback function when page changes                   |
+| `count`         | `number`                          | `undefined` | Total number of items                               |
+| `pageSize`      | `number`                          | `undefined` | Number of items per page                            |
+| `totalPages`    | `number`                          | `undefined` | Total number of pages (deprecated, use count + pageSize) |
+| `format`        | `'none' \| 'long'`                | `'none'`  | Format for displaying page info                       |
+| `simplified`    | `boolean`                         | `false`   | Show simplified pagination (prev/next only)           |
+| `asLink`        | `boolean`                         | `false`   | Render pagination buttons as links                    |
+| `getPageHref`   | `(page: number) => string`        | `undefined` | Custom href generator for pagination links          |
+| `siblingCount`  | `number`                          | `1`       | Number of page buttons to show on each side           |
+| `prevIcon`      | `React.ReactNode`                 | `'<'`     | Custom icon for previous button                       |
+| `nextIcon`      | `React.ReactNode`                 | `'>'`     | Custom icon for next button                           |
+| `size`          | `'sm' \| 'md' \| 'lg'`            | `'sm'`    | Size variant of pagination buttons                    |
+
+### Basic Pagination
+
+```jsx
+import { useState } from "react";
+import { Pagination } from "alope-ui";
+
+const BasicExample = () => {
+  const [currentPage, setCurrentPage] = useState(1);
+
+  return (
+    <Pagination
+      currentPage={currentPage}
+      count={100}
+      pageSize={10}
+      onPageChange={setCurrentPage}
+    />
+  );
+};
+```
+
+### Simplified Pagination
+
+```jsx
+const SimplifiedExample = () => {
+  const [currentPage, setCurrentPage] = useState(1);
+
+  return (
+    <Pagination
+      currentPage={currentPage}
+      count={100}
+      pageSize={10}
+      onPageChange={setCurrentPage}
+      simplified
+    />
+  );
+};
+```
+
+### Pagination with Format
+
+```jsx
+{/* None Format - Shows page numbers */}
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  format="none"
+  simplified
+/>
+
+{/* Long Format - Shows item range */}
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  format="long"
+  simplified
+/>
+```
+
+### Sizes
+
+```jsx
+{/* Small Size */}
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  size="sm"
+/>
+
+{/* Medium Size */}
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  size="md"
+/>
+
+{/* Large Size */}
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  size="lg"
+/>
+```
+
+### Custom Sibling Count
+
+```jsx
+{/* Show 2 page buttons on each side */}
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  siblingCount={2}
+/>
+```
+
+### Custom Icons
+
+```jsx
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  prevIcon={<ChevronLeft size={16} />}
+  nextIcon={<ChevronRight size={16} />}
+/>
+```
+
+### As Links
+
+```jsx
+<Pagination
+  currentPage={currentPage}
+  count={100}
+  pageSize={10}
+  onPageChange={setCurrentPage}
+  asLink
+  getPageHref={(page) => `/products?page=${page}`}
+/>
+```
+
+### Using TotalPages (Legacy)
+
+```jsx
+{/* This approach is deprecated, prefer using count + pageSize */}
+<Pagination
+  currentPage={currentPage}
+  totalPages={10}
+  onPageChange={setCurrentPage}
+/>
+```
+
+---
+
+## Table
+
+The Table component provides a flexible and feature-rich data table with support for custom rendering, row selection, striping, sticky headers, and responsive design.
+
+### Import
+
+```jsx
+import { Table } from "alope-ui";
+import type { Column } from "alope-ui";
+```
+
+### Props
+
+| Prop                   | Type                              | Default    | Description                                    |
+| ---------------------- | --------------------------------- | ---------- | ---------------------------------------------- |
+| `columns`              | `Column<T>[]`                     | `required` | Array of column configurations                 |
+| `data`                 | `T[]`                             | `required` | Array of data objects to display               |
+| `striped`              | `boolean`                         | `false`    | Enable alternating row colors                  |
+| `stripeColor`          | `string`                          | `undefined`| Custom color for striped rows                  |
+| `headerClassName`      | `string`                          | `""`       | CSS class for table header                     |
+| `dataColumnClassName`  | `string`                          | `""`       | CSS class for data cells                       |
+| `dataRowClassName`     | `string`                          | `""`       | CSS class for data rows                        |
+| `tableClassName`       | `string`                          | `""`       | CSS class for table element                    |
+| `captionClassName`     | `string`                          | `""`       | CSS class for caption                          |
+| `containerClassName`   | `string`                          | `""`       | CSS class for container                        |
+| `customEmptyData`      | `React.ReactNode`                 | `undefined`| Custom message when no data                    |
+| `size`                 | `'sm' \| 'md' \| 'lg'`            | `'md'`     | Size variant of table                          |
+| `caption`              | `string`                          | `undefined`| Table caption text                             |
+| `captionPosition`      | `'top' \| 'bottom'`               | `'bottom'` | Position of caption                            |
+| `stickyHeader`         | `boolean`                         | `false`    | Make header sticky on scroll                   |
+| `selectable`           | `boolean`                         | `false`    | Enable row selection with checkboxes           |
+| `onSelectionChange`    | `(selected: T[]) => void`         | `undefined`| Callback when selection changes                |
+| `selectedRows`         | `T[]`                             | `[]`       | Array of selected rows                         |
+
+### Column Type
+
+```typescript
+type Column<T> = {
+  header: string;
+  accessor: keyof T;
+  render?: (value: T[keyof T], row: T) => React.ReactNode;
+};
+```
+
+### Basic Table
+
+```jsx
+import { Table } from "alope-ui";
+import type { Column } from "alope-ui";
+
+type User = {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+};
+
+const columns: Column<User>[] = [
+  { header: "Name", accessor: "name" },
+  { header: "Email", accessor: "email" },
+  { header: "Role", accessor: "role" },
+];
+
+const data: User[] = [
+  { id: 1, name: "John Doe", email: "john@example.com", role: "Admin" },
+  { id: 2, name: "Jane Smith", email: "jane@example.com", role: "User" },
+  { id: 3, name: "Bob Johnson", email: "bob@example.com", role: "Manager" },
+];
+
+const BasicExample = () => {
+  return <Table columns={columns} data={data} />;
+};
+```
+
+### Striped Table
+
+```jsx
+<Table columns={columns} data={data} striped />
+
+{/* With custom stripe color */}
+<Table
+  columns={columns}
+  data={data}
+  striped
+  stripeColor="bg-blue-50 dark:bg-blue-900"
+/>
+```
+
+### Sizes
+
+```jsx
+{/* Small Size */}
+<Table columns={columns} data={data} size="sm" />
+
+{/* Medium Size */}
+<Table columns={columns} data={data} size="md" />
+
+{/* Large Size */}
+<Table columns={columns} data={data} size="lg" />
+```
+
+### Custom Rendering
+
+```jsx
+const columns: Column<User>[] = [
+  { header: "Name", accessor: "name" },
+  { header: "Email", accessor: "email" },
+  {
+    header: "Role",
+    accessor: "role",
+    render: (value, row) => (
+      <span
+        className={
+          value === "Admin"
+            ? "bg-red-100 text-red-800 px-2 py-1 rounded"
+            : "bg-blue-100 text-blue-800 px-2 py-1 rounded"
+        }
+      >
+        {value}
+      </span>
+    ),
+  },
+];
+
+<Table columns={columns} data={data} />;
+```
+
+### Selectable Rows
+
+```jsx
+import { useState } from "react";
+
+const SelectableExample = () => {
+  const [selectedRows, setSelectedRows] = useState<User[]>([]);
+
+  return (
+    <Table
+      columns={columns}
+      data={data}
+      selectable
+      selectedRows={selectedRows}
+      onSelectionChange={setSelectedRows}
+    />
+  );
+};
+```
+
+### Sticky Header
+
+```jsx
+<Table columns={columns} data={data} stickyHeader />
+```
+
+### With Caption
+
+```jsx
+{/* Caption at bottom */}
+<Table
+  columns={columns}
+  data={data}
+  caption="User Management Table"
+  captionPosition="bottom"
+/>
+
+{/* Caption at top */}
+<Table
+  columns={columns}
+  data={data}
+  caption="User Management Table"
+  captionPosition="top"
+/>
+```
+
+### Custom Empty State
+
+```jsx
+<Table
+  columns={columns}
+  data={[]}
+  customEmptyData={
+    <div className="flex flex-col items-center gap-2">
+      <span className="text-gray-500">No users found</span>
+      <button className="px-4 py-2 bg-blue-500 text-white rounded">
+        Add User
+      </button>
+    </div>
+  }
+/>
+```
+
+### Custom Styling
+
+```jsx
+<Table
+  columns={columns}
+  data={data}
+  containerClassName="shadow-lg rounded-lg"
+  tableClassName="border-2 border-blue-500"
+  headerClassName="bg-blue-600 text-white"
+  dataRowClassName="hover:bg-blue-50"
+  dataColumnClassName="text-gray-700"
+/>
+```
+
+### Complete Example
+
+```jsx
+import { useState } from "react";
+import { Table } from "alope-ui";
+import type { Column } from "alope-ui";
+
+type Product = {
+  id: number;
+  name: string;
+  price: number;
+  stock: number;
+  status: string;
+};
+
+const ProductTable = () => {
+  const [selectedRows, setSelectedRows] = useState<Product[]>([]);
+
+  const columns: Column<Product>[] = [
+    { header: "Product Name", accessor: "name" },
+    {
+      header: "Price",
+      accessor: "price",
+      render: (value) => `$${value.toFixed(2)}`,
+    },
+    { header: "Stock", accessor: "stock" },
+    {
+      header: "Status",
+      accessor: "status",
+      render: (value) => (
+        <span
+          className={
+            value === "Available"
+              ? "bg-green-100 text-green-800 px-2 py-1 rounded"
+              : "bg-gray-100 text-gray-800 px-2 py-1 rounded"
+          }
+        >
+          {value}
+        </span>
+      ),
+    },
+  ];
+
+  const data: Product[] = [
+    { id: 1, name: "Laptop", price: 999.99, stock: 15, status: "Available" },
+    { id: 2, name: "Mouse", price: 29.99, stock: 0, status: "Out of Stock" },
+    { id: 3, name: "Keyboard", price: 79.99, stock: 23, status: "Available" },
+  ];
+
+  return (
+    <Table
+      columns={columns}
+      data={data}
+      striped
+      selectable
+      selectedRows={selectedRows}
+      onSelectionChange={setSelectedRows}
+      stickyHeader
+      caption="Product Inventory"
+      size="md"
+    />
+  );
+};
+```
+
+---
+
+## Tooltip
+
+The Tooltip component displays informative text when hovering over an element, with customizable placement, styling, and animation options.
+
+### Import
+
+```jsx
+import { Tooltip } from "alope-ui";
+```
+
+### Props
+
+| Prop                | Type                                      | Default                           | Description                              |
+| ------------------- | ----------------------------------------- | --------------------------------- | ---------------------------------------- |
+| `children`          | `React.ReactNode`                         | `required`                        | Element that triggers the tooltip        |
+| `text`              | `string`                                  | `required`                        | Text content of the tooltip              |
+| `showArrow`         | `boolean`                                 | `true`                            | Show arrow pointing to trigger element   |
+| `placement`         | `'top' \| 'bottom' \| 'left' \| 'right'`  | `'top'`                           | Position of tooltip relative to trigger  |
+| `offset`            | `number`                                  | `8`                               | Distance from trigger element (in px)    |
+| `bgColor`           | `string`                                  | `'bg-gray-800 dark:bg-gray-600'`  | Background color class                   |
+| `isOpen`            | `boolean`                                 | `undefined`                       | Controlled visibility state              |
+| `onOpenChange`      | `(open: boolean) => void`                 | `undefined`                       | Callback when visibility changes         |
+| `disabled`          | `boolean`                                 | `false`                           | Disable tooltip functionality            |
+| `animationDuration` | `number`                                  | `300`                             | Animation duration (in ms)               |
+| `delay`             | `number`                                  | `700`                             | Delay before showing tooltip (in ms)     |
+
+### Basic Tooltip
+
+```jsx
+import { Tooltip } from "alope-ui";
+
+const BasicExample = () => {
+  return (
+    <Tooltip text="This is a helpful tooltip">
+      <button className="px-4 py-2 bg-blue-500 text-white rounded">
+        Hover me
+      </button>
+    </Tooltip>
+  );
+};
+```
+
+### Placement
+
+```jsx
+{/* Top Placement */}
+<Tooltip text="Tooltip on top" placement="top">
+  <button>Top</button>
+</Tooltip>
+
+{/* Bottom Placement */}
+<Tooltip text="Tooltip on bottom" placement="bottom">
+  <button>Bottom</button>
+</Tooltip>
+
+{/* Left Placement */}
+<Tooltip text="Tooltip on left" placement="left">
+  <button>Left</button>
+</Tooltip>
+
+{/* Right Placement */}
+<Tooltip text="Tooltip on right" placement="right">
+  <button>Right</button>
+</Tooltip>
+```
+
+### Without Arrow
+
+```jsx
+<Tooltip text="Tooltip without arrow" showArrow={false}>
+  <button>No Arrow</button>
+</Tooltip>
+```
+
+### Custom Offset
+
+```jsx
+{/* Small offset */}
+<Tooltip text="Close to element" offset={4}>
+  <button>Small Offset</button>
+</Tooltip>
+
+{/* Large offset */}
+<Tooltip text="Far from element" offset={16}>
+  <button>Large Offset</button>
+</Tooltip>
+```
+
+### Custom Background Color
+
+```jsx
+<Tooltip text="Blue tooltip" bgColor="bg-blue-600">
+  <button>Blue Tooltip</button>
+</Tooltip>
+
+<Tooltip text="Red tooltip" bgColor="bg-red-600">
+  <button>Red Tooltip</button>
+</Tooltip>
+
+<Tooltip text="Green tooltip" bgColor="bg-green-600">
+  <button>Green Tooltip</button>
+</Tooltip>
+```
+
+### Controlled Tooltip
+
+```jsx
+import { useState } from "react";
+
+const ControlledExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <Tooltip
+        text="Controlled tooltip"
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+      >
+        <button onClick={() => setIsOpen(!isOpen)}>
+          Click to toggle
+        </button>
+      </Tooltip>
+    </div>
+  );
+};
+```
+
+### Custom Animation
+
+```jsx
+{/* Fast animation */}
+<Tooltip text="Fast animation" animationDuration={150}>
+  <button>Fast</button>
+</Tooltip>
+
+{/* Slow animation */}
+<Tooltip text="Slow animation" animationDuration={600}>
+  <button>Slow</button>
+</Tooltip>
+```
+
+### Custom Delay
+
+```jsx
+{/* No delay */}
+<Tooltip text="Instant tooltip" delay={0}>
+  <button>No Delay</button>
+</Tooltip>
+
+{/* Long delay */}
+<Tooltip text="Patient tooltip" delay={1500}>
+  <button>Long Delay</button>
+</Tooltip>
+```
+
+### Disabled Tooltip
+
+```jsx
+<Tooltip text="This won't show" disabled>
+  <button>Disabled Tooltip</button>
+</Tooltip>
+```
+
+### With Icons
+
+```jsx
+import { Info, HelpCircle } from "lucide-react";
+
+<Tooltip text="Additional information about this feature">
+  <Info className="w-4 h-4 text-gray-500 cursor-help" />
+</Tooltip>
+
+<Tooltip text="Click for help documentation" placement="right">
+  <HelpCircle className="w-5 h-5 text-blue-500 cursor-pointer" />
+</Tooltip>
+```
+
+### Complete Example
+
+```jsx
+import { Tooltip } from "alope-ui";
+import { Info } from "lucide-react";
+
+const UserProfile = () => {
+  return (
+    <div className="flex items-center gap-4">
+      <div className="flex items-center gap-2">
+        <span>Username</span>
+        <Tooltip
+          text="Your username is visible to all users"
+          placement="top"
+          bgColor="bg-blue-600"
+          delay={500}
+        >
+          <Info className="w-4 h-4 text-gray-400 cursor-help" />
+        </Tooltip>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <span>Email</span>
+        <Tooltip
+          text="Your email is kept private and secure"
+          placement="right"
+          showArrow={false}
+          offset={12}
+        >
+          <Info className="w-4 h-4 text-gray-400 cursor-help" />
+        </Tooltip>
+      </div>
+
+      <Tooltip text="Click to edit your profile" placement="bottom">
+        <button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
+          Edit Profile
+        </button>
+      </Tooltip>
+    </div>
+  );
+};
+```
+
+---
+
+## Spinner
+
+The Spinner component displays an animated loading indicator with customizable size, color, duration, and thickness.
+
+### Import
+
+```jsx
+import { Spinner } from "alope-ui";
+```
+
+### Props
+
+| Prop        | Type                                                            | Default   | Description                           |
+| ----------- | --------------------------------------------------------------- | --------- | ------------------------------------- |
+| `size`      | `'sm' \| 'md' \| 'lg'`                                          | `'md'`    | Size of the spinner                   |
+| `color`     | `'primary' \| 'error' \| 'warning' \| 'success' \| 'info' \| 'secondary'` | `'primary'` | Color variant of the spinner    |
+| `className` | `string`                                                        | `""`      | Additional CSS classes                |
+| `duration`  | `number`                                                        | `1000`    | Animation duration (in ms)            |
+| `thickness` | `number`                                                        | `undefined` | Custom border thickness (in px)     |
+
+### Basic Spinner
+
+```jsx
+import { Spinner } from "alope-ui";
+
+const BasicExample = () => {
+  return <Spinner />;
+};
+```
+
+### Sizes
+
+```jsx
+{/* Small Size */}
+<Spinner size="sm" />
+
+{/* Medium Size */}
+<Spinner size="md" />
+
+{/* Large Size */}
+<Spinner size="lg" />
+```
+
+### Colors
+
+```jsx
+{/* Primary Color */}
+<Spinner color="primary" />
+
+{/* Error Color */}
+<Spinner color="error" />
+
+{/* Warning Color */}
+<Spinner color="warning" />
+
+{/* Success Color */}
+<Spinner color="success" />
+
+{/* Info Color */}
+<Spinner color="info" />
+
+{/* Secondary Color */}
+<Spinner color="secondary" />
+```
+
+### Custom Duration
+
+```jsx
+{/* Fast animation */}
+<Spinner duration={500} />
+
+{/* Slow animation */}
+<Spinner duration={2000} />
+```
+
+### Custom Thickness
+
+```jsx
+{/* Thin spinner */}
+<Spinner thickness={1} />
+
+{/* Thick spinner */}
+<Spinner thickness={6} />
+```
+
+### Combined Customization
+
+```jsx
+<Spinner size="lg" color="success" duration={1500} thickness={5} />
+```
+
+### With Custom Styling
+
+```jsx
+<Spinner className="mx-auto my-4" />
+
+<Spinner className="absolute top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2" />
+```
+
+### Loading States
+
+```jsx
+import { useState } from "react";
+
+const LoadingButton = () => {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleClick = async () => {
+    setIsLoading(true);
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    setIsLoading(false);
+  };
+
+  return (
+    <button
+      onClick={handleClick}
+      disabled={isLoading}
+      className="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50 flex items-center gap-2"
+    >
+      {isLoading && <Spinner size="sm" className="border-white" />}
+      {isLoading ? "Loading..." : "Submit"}
+    </button>
+  );
+};
+```
+
+### Centered Loading
+
+```jsx
+const CenteredLoading = () => {
+  return (
+    <div className="flex items-center justify-center h-64">
+      <Spinner size="lg" color="primary" />
+    </div>
+  );
+};
+```
+
+### With Text
+
+```jsx
+const LoadingWithText = () => {
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <Spinner size="lg" color="info" />
+      <p className="text-gray-600 dark:text-gray-400">Loading data...</p>
+    </div>
+  );
+};
+```
+
+### Complete Example
+
+```jsx
+import { useState, useEffect } from "react";
+import { Spinner } from "alope-ui";
+
+const DataFetcher = () => {
+  const [isLoading, setIsLoading] = useState(true);
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    const fetchData = async () => {
+      setIsLoading(true);
+      try {
+        // Simulate API call
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        setData({ message: "Data loaded successfully!" });
+      } catch (error) {
+        console.error(error);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchData();
+  }, []);
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center h-96 gap-4">
+        <Spinner size="lg" color="primary" duration={800} />
+        <p className="text-gray-600 dark:text-gray-400">
+          Fetching your data...
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4">
+      <h2 className="text-xl font-bold">{data?.message}</h2>
+    </div>
+  );
+};
+```
+
+---
+
+## Skeleton
+
+The Skeleton component displays a placeholder preview of content before the actual data is loaded, improving perceived performance and user experience.
+
+### Import
+
+```jsx
+import { Skeleton } from "alope-ui";
+```
+
+### Props
+
+| Prop        | Type                      | Default      | Description                                    |
+| ----------- | ------------------------- | ------------ | ---------------------------------------------- |
+| `width`     | `string`                  | `undefined`  | Width of the skeleton (CSS value)              |
+| `height`    | `string`                  | `undefined`  | Height of the skeleton (CSS value)             |
+| `rounded`   | `boolean`                 | `false`      | Apply rounded shape (full circle/pill)         |
+| `isLoading` | `boolean`                 | `true`       | Show skeleton or actual content                |
+| `children`  | `React.ReactNode`         | `undefined`  | Content to render when not loading             |
+| `animode`   | `'shimmer' \| 'flash'`    | `'flash'`    | Animation mode for the skeleton                |
+
+### Basic Skeleton
+
+```jsx
+import { Skeleton } from "alope-ui";
+
+const BasicExample = () => {
+  return <Skeleton width="200px" height="20px" />;
+};
+```
+
+### With Children
+
+```jsx
+import { useState, useEffect } from "react";
+
+const SkeletonWithChildren = () => {
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    setTimeout(() => setIsLoading(false), 2000);
+  }, []);
+
+  return (
+    <Skeleton isLoading={isLoading}>
+      <p>This content will show after loading</p>
+    </Skeleton>
+  );
+};
+```
+
+### Animation Modes
+
+```jsx
+{/* Flash animation */}
+<Skeleton width="200px" height="20px" animode="flash" />
+
+{/* Shimmer animation */}
+<Skeleton width="200px" height="20px" animode="shimmer" />
+```
+
+### Rounded Skeleton
+
+```jsx
+{/* Rounded rectangle */}
+<Skeleton width="100px" height="100px" rounded />
+
+{/* Avatar skeleton */}
+<Skeleton width="48px" height="48px" rounded />
+```
+
+### Different Sizes
+
+```jsx
+{/* Small */}
+<Skeleton width="100px" height="16px" />
+
+{/* Medium */}
+<Skeleton width="200px" height="20px" />
+
+{/* Large */}
+<Skeleton width="300px" height="24px" />
+
+{/* Full width */}
+<Skeleton width="100%" height="20px" />
+```
+
+### Text Skeleton
+
+```jsx
+const TextSkeleton = () => {
+  return (
+    <div className="space-y-2">
+      <Skeleton width="100%" height="20px" />
+      <Skeleton width="90%" height="20px" />
+      <Skeleton width="95%" height="20px" />
+      <Skeleton width="85%" height="20px" />
+    </div>
+  );
+};
+```
+
+### Card Skeleton
+
+```jsx
+const CardSkeleton = () => {
+  return (
+    <div className="border rounded-lg p-4 space-y-4">
+      {/* Image skeleton */}
+      <Skeleton width="100%" height="200px" />
+
+      {/* Title skeleton */}
+      <Skeleton width="70%" height="24px" />
+
+      {/* Description skeleton */}
+      <div className="space-y-2">
+        <Skeleton width="100%" height="16px" />
+        <Skeleton width="95%" height="16px" />
+        <Skeleton width="90%" height="16px" />
+      </div>
+
+      {/* Button skeleton */}
+      <Skeleton width="120px" height="40px" />
+    </div>
+  );
+};
+```
+
+### Avatar Skeleton
+
+```jsx
+const AvatarSkeleton = () => {
+  return (
+    <div className="flex items-center gap-3">
+      <Skeleton width="48px" height="48px" rounded />
+      <div className="space-y-2 flex-1">
+        <Skeleton width="150px" height="16px" />
+        <Skeleton width="100px" height="14px" />
+      </div>
+    </div>
+  );
+};
+```
+
+### List Skeleton
+
+```jsx
+const ListSkeleton = () => {
+  return (
+    <div className="space-y-4">
+      {[...Array(5)].map((_, i) => (
+        <div key={i} className="flex items-center gap-3">
+          <Skeleton width="40px" height="40px" rounded />
+          <div className="space-y-2 flex-1">
+            <Skeleton width="60%" height="16px" />
+            <Skeleton width="40%" height="14px" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+### Table Skeleton
+
+```jsx
+const TableSkeleton = () => {
+  return (
+    <div className="space-y-3">
+      {/* Header */}
+      <div className="grid grid-cols-4 gap-4">
+        <Skeleton width="100%" height="20px" />
+        <Skeleton width="100%" height="20px" />
+        <Skeleton width="100%" height="20px" />
+        <Skeleton width="100%" height="20px" />
+      </div>
+
+      {/* Rows */}
+      {[...Array(5)].map((_, i) => (
+        <div key={i} className="grid grid-cols-4 gap-4">
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="100%" height="16px" />
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+### Complete Example
+
+```jsx
+import { useState, useEffect } from "react";
+import { Skeleton } from "alope-ui";
+
+type User = {
+  id: number;
+  name: string;
+  email: string;
+  avatar: string;
+};
+
+const UserProfile = () => {
+  const [isLoading, setIsLoading] = useState(true);
+  const [user, setUser] = useState<User | null>(null);
+
+  useEffect(() => {
+    const fetchUser = async () => {
+      setIsLoading(true);
+      // Simulate API call
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      setUser({
+        id: 1,
+        name: "John Doe",
+        email: "john@example.com",
+        avatar: "/avatar.jpg",
+      });
+      setIsLoading(false);
+    };
+
+    fetchUser();
+  }, []);
+
+  if (isLoading) {
+    return (
+      <div className="max-w-md border rounded-lg p-6 space-y-4">
+        {/* Avatar and name skeleton */}
+        <div className="flex items-center gap-4">
+          <Skeleton width="64px" height="64px" rounded />
+          <div className="space-y-2 flex-1">
+            <Skeleton width="150px" height="20px" />
+            <Skeleton width="200px" height="16px" />
+          </div>
+        </div>
+
+        {/* Bio skeleton */}
+        <div className="space-y-2">
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="95%" height="16px" />
+          <Skeleton width="90%" height="16px" />
+        </div>
+
+        {/* Stats skeleton */}
+        <div className="flex gap-4">
+          <Skeleton width="80px" height="40px" />
+          <Skeleton width="80px" height="40px" />
+          <Skeleton width="80px" height="40px" />
+        </div>
+
+        {/* Button skeleton */}
+        <Skeleton width="100%" height="44px" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-md border rounded-lg p-6">
+      <div className="flex items-center gap-4 mb-4">
+        <img
+          src={user?.avatar}
+          alt={user?.name}
+          className="w-16 h-16 rounded-full"
+        />
+        <div>
+          <h2 className="text-xl font-bold">{user?.name}</h2>
+          <p className="text-gray-600">{user?.email}</p>
+        </div>
+      </div>
+      {/* Rest of the content */}
+    </div>
+  );
+};
+```
+
+---
+
+## Toggle
+
+The Toggle component provides an animated switch control for toggling between on/off states with various visual styles and sizes.
+
+### Import
+
+```jsx
+import { Toggle } from "alope-ui";
+```
+
+### Props
+
+| Prop                | Type                                                           | Default     | Description                              |
+| ------------------- | -------------------------------------------------------------- | ----------- | ---------------------------------------- |
+| `variant`           | `'primary' \| 'error' \| 'warning' \| 'success' \| 'info' \| 'secondary'` | `'primary'` | Color variant of the toggle              |
+| `customSize`        | `'sm' \| 'md' \| 'lg'`                                         | `'md'`      | Size of the toggle switch                |
+| `thumbShape`        | `'stadium' \| 'rounded'`                                       | `'stadium'` | Shape of the toggle thumb                |
+| `label`             | `string`                                                       | `undefined` | Label text displayed next to toggle      |
+| `wrapperClassName`  | `string`                                                       | `""`        | CSS class for wrapper element            |
+| `labelClassName`    | `string`                                                       | `""`        | CSS class for label text                 |
+| `...props`          | `InputHTMLAttributes<HTMLInputElement>`                        | -           | All standard HTML input attributes       |
+
+### Basic Toggle
+
+```jsx
+import { useState } from "react";
+import { Toggle } from "alope-ui";
+
+const BasicExample = () => {
+  const [isChecked, setIsChecked] = useState(false);
+
+  return (
+    <Toggle
+      checked={isChecked}
+      onChange={(e) => setIsChecked(e.target.checked)}
+    />
+  );
+};
+```
+
+### With Label
+
+```jsx
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  label="Enable notifications"
+/>
+```
+
+### Variants
+
+```jsx
+{/* Primary Variant */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  variant="primary"
+  label="Primary"
+/>
+
+{/* Error Variant */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  variant="error"
+  label="Error"
+/>
+
+{/* Warning Variant */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  variant="warning"
+  label="Warning"
+/>
+
+{/* Success Variant */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  variant="success"
+  label="Success"
+/>
+
+{/* Info Variant */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  variant="info"
+  label="Info"
+/>
+
+{/* Secondary Variant */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  variant="secondary"
+  label="Secondary"
+/>
+```
+
+### Sizes
+
+```jsx
+{/* Small Size */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  customSize="sm"
+  label="Small"
+/>
+
+{/* Medium Size */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  customSize="md"
+  label="Medium"
+/>
+
+{/* Large Size */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  customSize="lg"
+  label="Large"
+/>
+```
+
+### Thumb Shapes
+
+```jsx
+{/* Stadium Shape (Fully Rounded) */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  thumbShape="stadium"
+  label="Stadium"
+/>
+
+{/* Rounded Shape (Slightly Rounded) */}
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  thumbShape="rounded"
+  label="Rounded"
+/>
+```
+
+### Disabled State
+
+```jsx
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  disabled
+  label="Disabled toggle"
+/>
+```
+
+### Custom Styling
+
+```jsx
+<Toggle
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  label="Custom styled toggle"
+  wrapperClassName="bg-gray-100 p-4 rounded-lg"
+  labelClassName="text-lg font-bold text-blue-600"
+/>
+```
+
+### Complete Example
+
+```jsx
+import { useState } from "react";
+import { Toggle } from "alope-ui";
+
+const CompleteExample = () => {
+  const [settings, setSettings] = useState({
+    notifications: false,
+    darkMode: true,
+    autoSave: false,
+  });
+
+  const handleToggle = (key: string) => (e: React.ChangeEvent<HTMLInputElement>) => {
+    setSettings(prev => ({
+      ...prev,
+      [key]: e.target.checked
+    }));
+  };
+
+  return (
+    <div className="space-y-4">
+      <Toggle
+        checked={settings.notifications}
+        onChange={handleToggle('notifications')}
+        variant="primary"
+        customSize="md"
+        label="Enable notifications"
+      />
+      
+      <Toggle
+        checked={settings.darkMode}
+        onChange={handleToggle('darkMode')}
+        variant="secondary"
+        customSize="md"
+        label="Dark mode"
+      />
+      
+      <Toggle
+        checked={settings.autoSave}
+        onChange={handleToggle('autoSave')}
+        variant="success"
+        customSize="md"
+        label="Auto-save documents"
+      />
+    </div>
+  );
+};
+```
+
+---
+
+## FileUpload
+
+The FileUpload component provides a flexible file upload interface with support for drag-and-drop, file validation, preview, and two display modes (dropzone and text input).
+
+### Import
+
+```jsx
+import { FileUpload } from "alope-ui";
+```
+
+### Props
+
+| Prop             | Type                           | Default      | Description                                      |
+| ---------------- | ------------------------------ | ------------ | ------------------------------------------------ |
+| `onFilesChange`  | `(files: File[]) => void`      | `required`   | Callback fired when files change                 |
+| `acceptedFiles`  | `string`                       | `'image/*'`  | Accepted file types (MIME types or extensions)   |
+| `maxFiles`       | `number`                       | `1`          | Maximum number of files allowed                  |
+| `maxKiloByte`    | `number`                       | `2048`       | Maximum file size in kilobytes                   |
+| `mode`           | `'dropzone' \| 'textinput'`    | `'dropzone'` | Display mode of the file upload                  |
+| `clearable`      | `boolean`                      | `true`       | Show clear button on file previews               |
+| `inputLabel`     | `string`                       | `undefined`  | Label for text input mode button                 |
+| `helperText`     | `string`                       | `undefined`  | Helper text displayed below the input            |
+| `mediaCapture`   | `'user' \| 'environment'`      | `undefined`  | Camera capture mode (for mobile devices)         |
+
+### Basic FileUpload (Dropzone Mode)
+
+```jsx
+import { useState } from "react";
+import { FileUpload } from "alope-ui";
+
+const BasicExample = () => {
+  const [files, setFiles] = useState<File[]>([]);
+
+  return (
+    <FileUpload
+      onFilesChange={setFiles}
+    />
+  );
+};
+```
+
+### Text Input Mode
+
+```jsx
+<FileUpload
+  mode="textinput"
+  onFilesChange={setFiles}
+  inputLabel="Upload File"
+/>
+```
+
+### Multiple Files
+
+```jsx
+<FileUpload
+  maxFiles={5}
+  onFilesChange={setFiles}
+  helperText="You can upload up to 5 files"
+/>
+```
+
+### Custom File Types
+
+```jsx
+{/* Accept only images */}
+<FileUpload
+  acceptedFiles="image/*"
+  onFilesChange={setFiles}
+/>
+
+{/* Accept specific image types */}
+<FileUpload
+  acceptedFiles="image/png, image/jpeg, image/jpg"
+  onFilesChange={setFiles}
+/>
+
+{/* Accept PDFs */}
+<FileUpload
+  acceptedFiles="application/pdf"
+  onFilesChange={setFiles}
+/>
+
+{/* Accept by file extension */}
+<FileUpload
+  acceptedFiles=".pdf, .doc, .docx"
+  onFilesChange={setFiles}
+/>
+
+{/* Accept multiple types */}
+<FileUpload
+  acceptedFiles="image/*, .pdf, .doc"
+  onFilesChange={setFiles}
+/>
+```
+
+### File Size Limit
+
+```jsx
+{/* 5MB limit */}
+<FileUpload
+  maxKiloByte={5120}
+  onFilesChange={setFiles}
+  helperText="Maximum file size: 5MB"
+/>
+
+{/* 500KB limit */}
+<FileUpload
+  maxKiloByte={512}
+  onFilesChange={setFiles}
+  helperText="Maximum file size: 500KB"
+/>
+```
+
+### With Helper Text
+
+```jsx
+<FileUpload
+  onFilesChange={setFiles}
+  helperText="Accepted formats: PNG, JPG, JPEG. Max size: 2MB"
+/>
+```
+
+### Camera Capture (Mobile)
+
+```jsx
+{/* Use front camera */}
+<FileUpload
+  acceptedFiles="image/*"
+  mediaCapture="user"
+  onFilesChange={setFiles}
+/>
+
+{/* Use back camera */}
+<FileUpload
+  acceptedFiles="image/*"
+  mediaCapture="environment"
+  onFilesChange={setFiles}
+/>
+```
+
+### Non-clearable Files
+
+```jsx
+<FileUpload
+  onFilesChange={setFiles}
+  clearable={false}
+/>
+```
+
+### Complete Example with Dropzone Mode
+
+```jsx
+import { useState } from "react";
+import { FileUpload } from "alope-ui";
+
+const DropzoneExample = () => {
+  const [uploadedFiles, setUploadedFiles] = useState<File[]>([]);
+
+  const handleFilesChange = (files: File[]) => {
+    setUploadedFiles(files);
+    console.log('Uploaded files:', files);
+  };
+
+  return (
+    <div className="max-w-2xl mx-auto p-6">
+      <h2 className="text-xl font-bold mb-4">Upload Your Images</h2>
+      
+      <FileUpload
+        mode="dropzone"
+        acceptedFiles="image/png, image/jpeg, image/jpg"
+        maxFiles={3}
+        maxKiloByte={5120}
+        onFilesChange={handleFilesChange}
+        helperText="Upload up to 3 images. Max 5MB per file."
+      />
+      
+      {uploadedFiles.length > 0 && (
+        <div className="mt-4">
+          <p className="font-medium">Selected files:</p>
+          <ul className="list-disc list-inside">
+            {uploadedFiles.map((file, index) => (
+              <li key={index}>{file.name}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+### Complete Example with Text Input Mode
+
+```jsx
+import { useState } from "react";
+import { FileUpload } from "alope-ui";
+
+const TextInputExample = () => {
+  const [documents, setDocuments] = useState<File[]>([]);
+
+  return (
+    <div className="max-w-2xl mx-auto p-6">
+      <h2 className="text-xl font-bold mb-4">Upload Documents</h2>
+      
+      <FileUpload
+        mode="textinput"
+        acceptedFiles=".pdf, .doc, .docx"
+        maxFiles={5}
+        maxKiloByte={10240}
+        inputLabel="Choose Documents"
+        onFilesChange={setDocuments}
+        helperText="Accepted: PDF, DOC, DOCX. Max 10MB per file."
+      />
+    </div>
+  );
+};
+```
+
+---
+
+## Textarea
+
+The Textarea component provides a multi-line text input with optional auto-resize functionality, label, error messages, and dark mode support.
+
+### Import
+
+```jsx
+import { Textarea } from "alope-ui";
+import type { TextareaType } from "alope-ui";
+```
+
+### Props
+
+| Prop              | Type                                          | Default | Description                                      |
+| ----------------- | --------------------------------------------- | ------- | ------------------------------------------------ |
+| `label`           | `string`                                      | `undefined` | Label text displayed above textarea          |
+| `error`           | `string`                                      | `undefined` | Error message displayed below textarea       |
+| `autoResize`      | `boolean`                                     | `false` | Enable auto-resize based on content              |
+| `customClassName` | `string`                                      | `""`    | Custom CSS class for textarea element            |
+| `...props`        | `InputHTMLAttributes<HTMLTextAreaElement>`    | -       | All standard HTML textarea attributes            |
+
+### Basic Textarea
+
+```jsx
+import { useState } from "react";
+import { Textarea } from "alope-ui";
+
+const BasicExample = () => {
+  const [value, setValue] = useState("");
+
+  return (
+    <Textarea
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      placeholder="Enter your text here..."
+    />
+  );
+};
+```
+
+### With Label
+
+```jsx
+<Textarea
+  label="Description"
+  name="description"
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="Enter description..."
+/>
+```
+
+### With Error Message
+
+```jsx
+const [description, setDescription] = useState("");
+const [error, setError] = useState("");
+
+const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+  setDescription(e.target.value);
+  if (e.target.value.length < 10) {
+    setError("Description must be at least 10 characters");
+  } else {
+    setError("");
+  }
+};
+
+<Textarea
+  label="Description"
+  value={description}
+  onChange={handleChange}
+  error={error}
+  placeholder="Enter at least 10 characters..."
+/>
+```
+
+### Auto-Resize Textarea
+
+```jsx
+<Textarea
+  label="Auto-resizing textarea"
+  autoResize
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="This textarea grows as you type..."
+/>
+```
+
+### Disabled State
+
+```jsx
+<Textarea
+  label="Disabled textarea"
+  value="This textarea is disabled"
+  disabled
+/>
+```
+
+### Custom Styling
+
+```jsx
+<Textarea
+  label="Custom styled textarea"
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  customClassName="border-2 border-blue-500 focus:ring-blue-600 rounded-lg"
+  placeholder="Custom styled..."
+/>
+```
+
+### With Rows
+
+```jsx
+<Textarea
+  label="Fixed height textarea"
+  rows={8}
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="8 rows high..."
+/>
+```
+
+### Complete Example
+
+```jsx
+import { useState } from "react";
+import { Textarea } from "alope-ui";
+
+const CompleteExample = () => {
+  const [feedback, setFeedback] = useState("");
+  const [error, setError] = useState("");
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (feedback.length < 20) {
+      setError("Feedback must be at least 20 characters");
+      return;
+    }
+    
+    console.log("Feedback submitted:", feedback);
+    setFeedback("");
+    setError("");
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setFeedback(e.target.value);
+    if (error && e.target.value.length >= 20) {
+      setError("");
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="max-w-lg mx-auto p-6">
+      <h2 className="text-xl font-bold mb-4">Share Your Feedback</h2>
+      
+      <Textarea
+        label="Feedback"
+        name="feedback"
+        value={feedback}
+        onChange={handleChange}
+        error={error}
+        autoResize
+        placeholder="Tell us what you think... (minimum 20 characters)"
+        customClassName="mb-4"
+      />
+      
+      <p className="text-sm text-gray-500 mb-4">
+        Character count: {feedback.length}
+      </p>
+      
+      <button
+        type="submit"
+        className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
+      >
+        Submit Feedback
+      </button>
+    </form>
+  );
+};
+```
+
+### Form Integration Example
+
+```jsx
+import { useState } from "react";
+import { Textarea } from "alope-ui";
+
+const FormExample = () => {
+  const [formData, setFormData] = useState({
+    name: "",
+    message: "",
+    comments: ""
+  });
+
+  const handleChange = (field: string) => (
+    e: React.ChangeEvent<HTMLTextAreaElement>
+  ) => {
+    setFormData(prev => ({
+      ...prev,
+      [field]: e.target.value
+    }));
+  };
+
+  return (
+    <div className="space-y-4 max-w-lg mx-auto p-6">
+      <Textarea
+        label="Message"
+        name="message"
+        value={formData.message}
+        onChange={handleChange('message')}
+        placeholder="Your message..."
+        rows={4}
+      />
+      
+      <Textarea
+        label="Additional Comments"
+        name="comments"
+        value={formData.comments}
+        onChange={handleChange('comments')}
+        placeholder="Any additional comments..."
+        autoResize
+      />
+    </div>
+  );
+};
+```
+
+---
+
+## Tabs
+
+The Tabs component provides a tabbed navigation interface for organizing and displaying content in separate panels.
+
+### Import
+
+```jsx
+import { Tabs } from "alope-ui";
+import type { Tabs as TabType } from "alope-ui";
+```
+
+### Props
+
+| Prop                 | Type                                                | Default  | Description                              |
+| -------------------- | --------------------------------------------------- | -------- | ---------------------------------------- |
+| `tabs`               | `TabType[]`                                         | `required` | Array of tab objects                   |
+| `variant`            | `'line' \| 'solid' \| 'subtle' \| 'inline' \| 'outline' \| 'plain'` | `'line'` | Visual variant style    |
+| `fitted`             | `boolean`                                           | `false`  | Make tabs fill available width           |
+| `wrapperClassName`   | `string`                                            | `""`     | Wrapper container CSS class              |
+| `buttonClassName`    | `string`                                            | `""`     | Tab button CSS class                     |
+| `activeClassName`    | `string`                                            | `""`     | Active tab CSS class                     |
+| `inactiveClassName`  | `string`                                            | `""`     | Inactive tab CSS class                   |
+| `activeTab`          | `number`                                            | `undefined` | Controlled active tab index           |
+| `onTabChange`        | `(index: number) => void`                           | `undefined` | Callback when tab changes             |
+
+### Tab Object Type
+
+```typescript
+type Tabs = {
+  label: string;
+  content: React.ReactNode;
+  disabled?: boolean;
+  link?: string;
+}
+```
+
+### Basic Tabs
+
+```jsx
+import { Tabs } from "alope-ui";
+
+const BasicExample = () => {
+  const tabs = [
+    {
+      label: "Profile",
+      content: <div>Profile content here</div>,
+    },
+    {
+      label: "Settings",
+      content: <div>Settings content here</div>,
+    },
+    {
+      label: "Notifications",
+      content: <div>Notifications content here</div>,
+    },
+  ];
+
+  return <Tabs tabs={tabs} />;
+};
+```
+
+### Variants
+
+```jsx
+{/* Line Variant */}
+<Tabs tabs={tabs} variant="line" />
+
+{/* Solid Variant */}
+<Tabs tabs={tabs} variant="solid" />
+
+{/* Subtle Variant */}
+<Tabs tabs={tabs} variant="subtle" />
+
+{/* Inline Variant */}
+<Tabs tabs={tabs} variant="inline" />
+
+{/* Outline Variant */}
+<Tabs tabs={tabs} variant="outline" />
+
+{/* Plain Variant */}
+<Tabs tabs={tabs} variant="plain" />
+```
+
+### Fitted Tabs
+
+```jsx
+{/* Tabs will fill the available width equally */}
+<Tabs tabs={tabs} fitted />
+```
+
+### Controlled Tabs
+
+```jsx
+import { useState } from "react";
+import { Tabs } from "alope-ui";
+
+const ControlledExample = () => {
+  const [activeTab, setActiveTab] = useState(0);
+
+  const tabs = [
+    {
+      label: "Tab 1",
+      content: <div>Content 1</div>,
+    },
+    {
+      label: "Tab 2",
+      content: <div>Content 2</div>,
+    },
+  ];
+
+  return (
+    <Tabs
+      tabs={tabs}
+      activeTab={activeTab}
+      onTabChange={setActiveTab}
+    />
+  );
+};
+```
+
+### Disabled Tabs
+
+```jsx
+const tabs = [
+  {
+    label: "Active Tab",
+    content: <div>Active content</div>,
+  },
+  {
+    label: "Disabled Tab",
+    content: <div>This content won't show</div>,
+    disabled: true,
+  },
+];
+
+<Tabs tabs={tabs} />
+```
+
+### Tabs with Links
+
+```jsx
+const tabs = [
+  {
+    label: "Dashboard",
+    content: <div>Dashboard content</div>,
+    link: "/dashboard",
+  },
+  {
+    label: "Profile",
+    content: <div>Profile content</div>,
+    link: "/profile",
+  },
+];
+
+<Tabs tabs={tabs} />
+```
+
+### Custom Styling
+
+```jsx
+<Tabs
+  tabs={tabs}
+  variant="solid"
+  wrapperClassName="bg-gray-100 dark:bg-gray-800"
+  buttonClassName="text-base"
+  activeClassName="font-bold"
+  inactiveClassName="opacity-70"
+/>
+```
+
+### Complete Example
+
+```jsx
+import { useState } from "react";
+import { Tabs } from "alope-ui";
+
+const CompleteExample = () => {
+  const [activeTab, setActiveTab] = useState(0);
+
+  const tabs = [
+    {
+      label: "Overview",
+      content: (
+        <div className="p-4">
+          <h2 className="text-xl font-bold mb-2">Overview</h2>
+          <p>Dashboard overview content goes here.</p>
+        </div>
+      ),
+    },
+    {
+      label: "Analytics",
+      content: (
+        <div className="p-4">
+          <h2 className="text-xl font-bold mb-2">Analytics</h2>
+          <p>Analytics and statistics content.</p>
+        </div>
+      ),
+    },
+    {
+      label: "Reports",
+      content: (
+        <div className="p-4">
+          <h2 className="text-xl font-bold mb-2">Reports</h2>
+          <p>Reports and data visualization.</p>
+        </div>
+      ),
+    },
+    {
+      label: "Settings",
+      content: (
+        <div className="p-4">
+          <h2 className="text-xl font-bold mb-2">Settings</h2>
+          <p>Configuration and preferences.</p>
+        </div>
+      ),
+      disabled: true,
+    },
+  ];
+
+  return (
+    <Tabs
+      tabs={tabs}
+      variant="subtle"
+      fitted
+      activeTab={activeTab}
+      onTabChange={setActiveTab}
+    />
+  );
+};
+```
+
+---
+
+## Avatar
+
+The Avatar component displays user profile images with fallback initials, status indicators, and various styling options.
+
+### Import
+
+```jsx
+import { Avatar } from "alope-ui";
+```
+
+### Props
+
+| Prop              | Type                                                      | Default     | Description                           |
+| ----------------- | --------------------------------------------------------- | ----------- | ------------------------------------- |
+| `imageSrc`        | `string`                                                  | `undefined` | URL of the avatar image               |
+| `fallbackName`    | `string`                                                  | `undefined` | Name to generate initials from        |
+| `fallbackColor`   | `'primary' \| 'error' \| 'warning' \| 'success' \| 'info' \| 'secondary'` | `'primary'` | Background color for fallback |
+| `shape`           | `'sharp' \| 'cornered' \| 'rounded'`                      | `'rounded'` | Shape of the avatar                   |
+| `variant`         | `'solid' \| 'outline'`                                    | `'solid'`   | Visual variant style                  |
+| `size`            | `'sm' \| 'md' \| 'lg'`                                    | `'md'`      | Size of the avatar                    |
+| `ring`            | `boolean`                                                 | `false`     | Show ring around avatar               |
+| `ringClassName`   | `string`                                                  | `""`        | Custom ring CSS class                 |
+| `alt`             | `string`                                                  | `'avatar'`  | Alt text for image                    |
+| `status`          | `'online' \| 'offline'`                                   | `undefined` | Status indicator                      |
+| `className`       | `string`                                                  | `""`        | Additional CSS class                  |
+
+### Basic Avatar
+
+```jsx
+import { Avatar } from "alope-ui";
+
+const BasicExample = () => {
+  return (
+    <Avatar
+      imageSrc="https://i.pravatar.cc/150?img=1"
+      alt="User Avatar"
+    />
+  );
+};
+```
+
+### Fallback with Initials
+
+```jsx
+{/* Avatar with fallback name */}
+<Avatar fallbackName="John Doe" />
+
+{/* Avatar with no image (shows initials) */}
+<Avatar 
+  imageSrc="invalid-url.jpg" 
+  fallbackName="Jane Smith" 
+/>
+```
+
+### Sizes
+
+```jsx
+{/* Small */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  size="sm" 
+/>
+
+{/* Medium */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  size="md" 
+/>
+
+{/* Large */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  size="lg" 
+/>
+```
+
+### Shapes
+
+```jsx
+{/* Sharp corners */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  shape="sharp" 
+/>
+
+{/* Cornered (slightly rounded) */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  shape="cornered" 
+/>
+
+{/* Rounded (circular) */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  shape="rounded" 
+/>
+```
+
+### Variants
+
+```jsx
+{/* Solid variant */}
+<Avatar 
+  fallbackName="John Doe" 
+  variant="solid" 
+/>
+
+{/* Outline variant */}
+<Avatar 
+  fallbackName="John Doe" 
+  variant="outline" 
+/>
+```
+
+### Fallback Colors
+
+```jsx
+{/* Primary color */}
+<Avatar fallbackName="John Doe" fallbackColor="primary" />
+
+{/* Error color */}
+<Avatar fallbackName="John Doe" fallbackColor="error" />
+
+{/* Warning color */}
+<Avatar fallbackName="John Doe" fallbackColor="warning" />
+
+{/* Success color */}
+<Avatar fallbackName="John Doe" fallbackColor="success" />
+
+{/* Info color */}
+<Avatar fallbackName="John Doe" fallbackColor="info" />
+
+{/* Secondary color */}
+<Avatar fallbackName="John Doe" fallbackColor="secondary" />
+```
+
+### With Ring
+
+```jsx
+{/* Default ring */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  ring 
+/>
+
+{/* Custom ring color */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  ring 
+  ringClassName="ring-success dark:ring-success-dark"
+/>
+```
+
+### Status Indicator
+
+```jsx
+{/* Online status */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  status="online" 
+/>
+
+{/* Offline status */}
+<Avatar 
+  imageSrc="https://i.pravatar.cc/150?img=1" 
+  status="offline" 
+/>
+```
+
+### Complete Example
+
+```jsx
+import { Avatar } from "alope-ui";
+
+const CompleteExample = () => {
+  return (
+    <div className="flex gap-4">
+      <Avatar
+        imageSrc="https://i.pravatar.cc/150?img=1"
+        fallbackName="John Doe"
+        size="lg"
+        shape="rounded"
+        ring
+        status="online"
+        alt="John Doe Avatar"
+      />
+      
+      <Avatar
+        imageSrc="https://i.pravatar.cc/150?img=2"
+        fallbackName="Jane Smith"
+        size="lg"
+        shape="rounded"
+        ring
+        status="offline"
+        alt="Jane Smith Avatar"
+      />
+    </div>
+  );
+};
+```
+
+## AvatarGroup
+
+The AvatarGroup component displays multiple avatars in an overlapping stack with a counter for additional avatars.
+
+### Import
+
+```jsx
+import { AvatarGroup } from "alope-ui";
+import type { AvatarGroupProps } from "alope-ui";
+```
+
+### Props
+
+| Prop          | Type              | Default  | Description                              |
+| ------------- | ----------------- | -------- | ---------------------------------------- |
+| `avatars`     | `AvatarProps[]`   | `required` | Array of avatar configurations         |
+| `maxVisible`  | `number`          | `3`      | Maximum number of visible avatars        |
+| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of all avatars in the group    |
+| `overlap`     | `string`          | `'-ml-3'` | CSS class for overlap spacing           |
+| `className`   | `string`          | `""`     | Additional CSS class                     |
+
+### Basic AvatarGroup
+
+```jsx
+import { AvatarGroup } from "alope-ui";
+
+const BasicGroupExample = () => {
+  const avatars = [
+    { imageSrc: "https://i.pravatar.cc/150?img=1", fallbackName: "John Doe" },
+    { imageSrc: "https://i.pravatar.cc/150?img=2", fallbackName: "Jane Smith" },
+    { imageSrc: "https://i.pravatar.cc/150?img=3", fallbackName: "Bob Wilson" },
+  ];
+
+  return <AvatarGroup avatars={avatars} />;
+};
+```
+
+### With Max Visible Limit
+
+```jsx
+const avatars = [
+  { imageSrc: "https://i.pravatar.cc/150?img=1", fallbackName: "User 1" },
+  { imageSrc: "https://i.pravatar.cc/150?img=2", fallbackName: "User 2" },
+  { imageSrc: "https://i.pravatar.cc/150?img=3", fallbackName: "User 3" },
+  { imageSrc: "https://i.pravatar.cc/150?img=4", fallbackName: "User 4" },
+  { imageSrc: "https://i.pravatar.cc/150?img=5", fallbackName: "User 5" },
+];
+
+{/* Show only 3 avatars, rest shown as "+2" */}
+<AvatarGroup avatars={avatars} maxVisible={3} />
+```
+
+### Different Sizes
+
+```jsx
+{/* Small size */}
+<AvatarGroup avatars={avatars} size="sm" />
+
+{/* Medium size */}
+<AvatarGroup avatars={avatars} size="md" />
+
+{/* Large size */}
+<AvatarGroup avatars={avatars} size="lg" />
+```
+
+### Custom Overlap
+
+```jsx
+{/* More overlap */}
+<AvatarGroup avatars={avatars} overlap="-ml-4" />
+
+{/* Less overlap */}
+<AvatarGroup avatars={avatars} overlap="-ml-2" />
+
+{/* No overlap */}
+<AvatarGroup avatars={avatars} overlap="" />
+```
+
+### Complete AvatarGroup Example
+
+```jsx
+import { AvatarGroup } from "alope-ui";
+
+const CompleteGroupExample = () => {
+  const teamMembers = [
+    { 
+      imageSrc: "https://i.pravatar.cc/150?img=1", 
+      fallbackName: "John Doe",
+      status: "online"
+    },
+    { 
+      imageSrc: "https://i.pravatar.cc/150?img=2", 
+      fallbackName: "Jane Smith",
+      status: "online"
+    },
+    { 
+      imageSrc: "https://i.pravatar.cc/150?img=3", 
+      fallbackName: "Bob Wilson",
+      status: "offline"
+    },
+    { 
+      fallbackName: "Alice Brown",
+      fallbackColor: "success"
+    },
+    { 
+      fallbackName: "Charlie Davis",
+      fallbackColor: "info"
+    },
+  ];
+
+  return (
+    <AvatarGroup
+      avatars={teamMembers}
+      maxVisible={3}
+      size="md"
+      overlap="-ml-3"
+    />
+  );
+};
+```
+
+---
+
 ## 💡 Contributing
 
 We welcome contributions! If you want to add features, fix bugs, or improve documentation, feel free to fork this project and submit a pull request.
@@ -1717,4 +4109,4 @@ MIT License – Free to use, modify, and distribute.
 
 ## 🙌 Thank You
 
-Thank you for using **ALOPE UI Library**. We hope this helps you build beautiful and functional user interfaces with ease.
+Thank you for using **ALOPE UI Library**. We hope this helps you build beautiful and functional user interfaces with ease.