@binarycastle/table

A comprehensive, responsive Vue 3 table component library with sorting, pagination, search, and column management features. Built with TypeScript and styled with Tailwind CSS.

✨ Features

• 🔍 Global Search - Search across all table data
• 📊 Column Sorting - Sort by multiple columns with visual indicators
• 📄 Pagination - Built-in pagination with customizable page sizes
• 👁️ Column Visibility - Toggle column visibility with built-in column manager
• 📱 Responsive Design - Mobile-friendly responsive table layout
• 🎨 Customizable Slots - Custom cell rendering with Vue slots
• 🔧 Data Adapters - Support for different backend API formats (Laravel included)
• 📝 TypeScript Support - Full TypeScript support with type definitions
• 🎯 Auto-increment Columns - Special column type for row numbering

📦 Installation

npm install @binarycastle/table

yarn add @binarycastle/table

🚀 Quick Start

1. Import the component and styles

import { BCTable, Column } from '@binarycastle/table'
import '@binarycastle/table/dist/binary-castle-table.css'

2. Basic Usage

<template>
  <BCTable 
    :columns="columns" 
    :http-service="httpService" 
    fetch-url="api/users"
  />
</template>

<script setup lang="ts">
import { BCTable, Column } from '@binarycastle/table'
import axios from 'axios'

const httpService = axios.create({
  baseURL: 'https://your-api.com'
})

const columns = [
  new Column({ label: 'Name', field: 'name', sortable: true }),
  new Column({ label: 'Email', field: 'email', sortable: true }),
  new Column({ label: 'Role', field: 'role' }),
  new Column({ label: 'Actions', field: 'actions' })
]
</script>

📚 API Reference

BCTable Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | columns | Column[] | ✅ | - | Array of column definitions | | httpService | AxiosInstance | ✅ | - | Axios instance for API calls | | fetchUrl | string | ✅ | - | API endpoint to fetch data | | multiSort | boolean | ❌ | false | Enable multi-column sorting | | instantSearch | boolean | ❌ | true | Enable instant search | | perPage | number | ❌ | 10 | Default items per page | | perPageOptions | number[] | ❌ | [10, 25, 50, 100] | Available page size options | | dataAdapter | BaseAdapter | ❌ | LaravelAdapter | Data adapter for API response format |

Column Configuration

new Column({
  label: string,        // Column header text
  field: string,        // Data field path (supports nested: 'user.profile.name')
  sortable?: boolean,   // Enable sorting (default: false)
  searchable?: boolean, // Include in search (default: false)
  visible?: boolean,    // Show/hide column (default: true)
  width?: string        // Column width (default: 'auto')
})

AutoIncrementColumn

For row numbering:

import { AutoIncrementColumn } from '@binarycastle/table'

const columns = [
  new AutoIncrementColumn({ label: '#', field: 'number' }),
  // ... other columns
]

🔧 Advanced Usage

Custom Cell Rendering

Use Vue slots to customize cell content:

<template>
  <BCTable :columns="columns" :http-service="httpService" fetch-url="api/users">
    <!-- Custom action buttons -->
    <template #actions="{ item }">
      <div class="flex gap-2">
        <button @click="editUser(item.id)" class="btn-primary">
          Edit
        </button>
        <button @click="deleteUser(item.id)" class="btn-danger">
          Delete
        </button>
      </div>
    </template>
    
    <!-- Custom status badge -->
    <template #status="{ item }">
      <span :class="getStatusClass(item.status)">
        {{ item.status }}
      </span>
    </template>
    
    <!-- Custom user info with avatar -->
    <template #user="{ item }">
      <div class="flex items-center">
        <img :src="item.avatar" class="w-8 h-8 rounded-full mr-2" />
        <span>{{ item.name }}</span>
      </div>
    </template>
  </BCTable>
</template>

Nested Field Access

Access nested object properties using dot notation:

const columns = [
  new Column({ label: 'User Name', field: 'user.profile.firstName' }),
  new Column({ label: 'Company', field: 'user.company.name' }),
  new Column({ label: 'Address', field: 'user.address.street' })
]

Custom Data Adapter

Create custom adapters for different API response formats:

import { BaseAdapter } from '@binarycastle/table'

class CustomAdapter extends BaseAdapter {
  transformResponse(response: any) {
    return {
      data: response.results,           // Your data array
      pagination: {
        current_page: response.page,
        last_page: response.totalPages,
        per_page: response.limit,
        total: response.totalCount
      }
    }
  }
}

// Use in component
const dataAdapter = new CustomAdapter()

Programmatic Control

Access table methods via template ref:

<template>
  <BCTable 
    ref="tableRef"
    :columns="columns" 
    :http-service="httpService" 
    fetch-url="api/users"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const tableRef = ref()

// Refresh table data
const refreshTable = () => {
  tableRef.value?.fetchDataThroughUrl()
}
</script>

🎨 Styling

The component is built with Tailwind CSS. You can customize the appearance by:

1. Override CSS classes - Target specific classes used in the component
2. Tailwind configuration - Modify your Tailwind config to change design tokens
3. Custom CSS - Add custom styles after importing the component styles

📋 Expected API Response Format

The default Laravel adapter expects responses in this format:

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "created_at": "2023-01-01T00:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 5,
  "per_page": 10,
  "total": 50
}

For different API formats, implement a custom BaseAdapter.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the LGPL-3.0-or-later License.

👨‍💻 Author

binarycastle

• Website: binarycastle.net
• Email: [email protected]

Made with ❤️ by binarycastle