https://github.com/simonepriuli/shadcn-aizoon
https://github.com/simonepriuli/shadcn-aizoon
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/simonepriuli/shadcn-aizoon
- Owner: simonepriuli
- Created: 2025-09-12T09:36:12.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-12T12:44:32.000Z (10 months ago)
- Last Synced: 2025-09-12T14:57:13.336Z (10 months ago)
- Language: TypeScript
- Size: 103 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SuperTable - Advanced Data Table Component
A powerful, type-safe data table component built with React, TypeScript, TanStack Table, and shadcn/ui. Features advanced filtering, sorting, pagination, and a flexible column builder API.
## ✨ Features
- 🔍 **Advanced Filtering** - Text, number, option, multi-option, and date filters
- 📊 **Sorting** - Clickable column headers with visual indicators
- 📄 **Pagination** - Built-in pagination with customizable page sizes
- 🎨 **Type Safety** - Full TypeScript support with IntelliSense
- 🏗️ **Column Builder** - Functional API for creating columns
- 🎯 **Flexible** - Support for custom cells and filters
- 🎨 **shadcn/ui** - Beautiful, accessible UI components
## 🚀 Quick Start
### Basic Usage
```typescript
import { SuperTable, generateColumns } from './components/supertable';
import { Mail, DollarSign, CheckCircle } from 'lucide-react';
// Define your data type
type Payment = {
id: string;
amount: number;
status: "pending" | "processing" | "success" | "failed";
email: string;
};
// Create sample data
const data: Payment[] = [
{ id: "1", amount: 100, status: "pending", email: "user@example.com" },
{ id: "2", amount: 200, status: "success", email: "admin@example.com" },
// ... more data
];
// Define columns using the builder pattern
const columns = generateColumns((b) => [
b.text("email", {
header: "Email",
displayName: "Email Address",
icon: Mail,
}),
b.number("amount", {
header: "Amount",
displayName: "Amount",
icon: DollarSign,
min: 0,
max: 1000,
}),
b.option("status", {
header: "Status",
displayName: "Status",
icon: CheckCircle,
options: [
{ label: "Pending", value: "pending", icon: Clock },
{ label: "Success", value: "success", icon: CheckCircle },
],
}),
]);
// Use the table
function App() {
return (
);
}
```
## 📚 API Reference
### SuperTable Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `{ tstColumns, filterColumns }` | Required | Generated columns from `generateColumns()` |
| `data` | `TData[]` | Required | Array of data objects |
| `enablePagination` | `boolean` | `false` | Enable pagination controls |
| `enableSorting` | `boolean` | `false` | Enable column sorting |
| `pageSize` | `number` | `10` | Number of rows per page |
### Column Builder Methods
#### `b.text(id, config)`
Creates a text column with text-based filtering.
```typescript
b.text("email", {
header: "Email",
displayName: "Email Address",
icon: Mail,
enableSorting: true, // Optional, defaults to true
})
```
#### `b.number(id, config)`
Creates a number column with range filtering.
```typescript
b.number("amount", {
header: "Amount",
displayName: "Amount",
icon: DollarSign,
min: 0, // Optional minimum value
max: 1000, // Optional maximum value
enableSorting: true, // Optional, defaults to true
})
```
#### `b.option(id, config)`
Creates a single-select dropdown column.
```typescript
b.option("status", {
header: "Status",
displayName: "Status",
icon: CheckCircle,
options: [
{ label: "Pending", value: "pending", icon: Clock },
{ label: "Success", value: "success", icon: CheckCircle },
],
enableSorting: true, // Optional, defaults to true
})
```
#### `b.multiOption(id, config)`
Creates a multi-select checkbox column.
```typescript
b.multiOption("tags", {
header: "Tags",
displayName: "Tags",
icon: Tag,
options: [
{ label: "Frontend", value: "frontend", icon: Code },
{ label: "Backend", value: "backend", icon: Server },
],
enableSorting: true, // Optional, defaults to true
})
```
#### `b.date(id, config)`
Creates a date column with date filtering.
```typescript
b.date("createdAt", {
header: "Created At",
displayName: "Created Date",
icon: Calendar,
enableSorting: true, // Optional, defaults to true
})
```
#### `b.custom(id, config)`
Creates a custom column with full control.
```typescript
b.custom("actions", {
header: "Actions",
cell: ({ row }) => (
handleEdit(row.original)}>
Edit
),
enableSorting: false, // Usually disabled for action columns
// Optional: Add custom filtering
filterConfig: {
type: 'text',
displayName: 'Search Actions',
icon: Search,
},
})
```
#### `b.display(id, config)`
Creates a display-only column without filtering.
```typescript
b.display("id", {
header: "ID",
cell: ({ row }) => (
{row.getValue("id")}
),
enableSorting: false, // Defaults to false
})
```
## 🎨 Advanced Examples
### Custom Filter with Complex Data
```typescript
const columns = generateColumns((b) => [
b.text("name", {
header: "Name",
displayName: "Full Name",
icon: User,
}),
// Custom column with complex filtering
b.custom("department", {
header: "Department",
displayName: "Department",
icon: Building,
enableSorting: true,
filterConfig: {
type: 'multiOption',
displayName: 'Departments',
icon: Building,
options: [
{ label: "Engineering", value: "engineering", icon: Code },
{ label: "Design", value: "design", icon: Palette },
{ label: "Marketing", value: "marketing", icon: Megaphone },
{ label: "Sales", value: "sales", icon: TrendingUp },
],
},
cell: ({ row }) => (
{row.original.department}
),
}),
// Action column with custom cell
b.custom("actions", {
header: "Actions",
cell: ({ row }) => (
⋮
handleEdit(row.original)}>
Edit
handleDelete(row.original)}>
Delete
),
enableSorting: false,
}),
]);
```
### Mixed Column Types
```typescript
const columns = generateColumns((b) => [
// Sortable and filterable columns
b.text("name", {
header: "Product Name",
displayName: "Product Name",
icon: Package,
}),
b.number("price", {
header: "Price",
displayName: "Price",
icon: DollarSign,
min: 0,
max: 10000,
}),
b.option("category", {
header: "Category",
displayName: "Category",
icon: Tag,
options: categoryOptions,
}),
// Display-only columns
b.display("id", {
header: "ID",
cell: ({ row }) => (
#{row.getValue("id")}
),
}),
b.display("image", {
header: "Image",
cell: ({ row }) => (
),
}),
]);
```
## 🔧 Configuration Options
### Filter Types
| Type | Description | Use Case |
|------|-------------|----------|
| `text` | Text input search | Names, descriptions, emails |
| `number` | Number range with min/max | Prices, quantities, scores |
| `option` | Single select dropdown | Status, category, priority |
| `multiOption` | Multi-select checkboxes | Tags, permissions, features |
| `date` | Date picker | Created date, due date, timestamp |
### Sorting Behavior
- **Enabled by default** for: `text`, `number`, `option`, `multiOption`, `date`, `custom`
- **Disabled by default** for: `display`
- **Override** with `enableSorting: boolean` in any column config
### Pagination
```typescript
```
## 🎯 Best Practices
### 1. Use Appropriate Column Types
```typescript
// ✅ Good - Use specific column types
b.text("email", { /* ... */ })
b.number("amount", { /* ... */ })
b.option("status", { /* ... */ })
// ❌ Avoid - Don't use custom for simple cases
b.custom("email", { /* ... */ })
```
### 2. Disable Sorting for Action Columns
```typescript
// ✅ Good - Actions shouldn't be sortable
b.custom("actions", {
/* ... */,
enableSorting: false,
})
b.display("id", {
/* ... */,
// enableSorting defaults to false
})
```
### 3. Use Display Columns for Simple Content
```typescript
// ✅ Good - Simple display content
b.display("avatar", {
header: "Avatar",
cell: ({ row }) => 
,
})
// ❌ Avoid - Don't use custom for simple display
b.custom("avatar", { /* ... */ })
```
### 4. Provide Meaningful Icons
```typescript
// ✅ Good - Descriptive icons
b.text("email", { icon: Mail })
b.number("amount", { icon: DollarSign })
b.option("status", { icon: CheckCircle })
// ❌ Avoid - Generic icons
b.text("email", { icon: Circle })
```
## 🐛 Troubleshooting
### Common Issues
**Q: Sorting not working?**
A: Make sure `enableSorting={true}` is passed to the SuperTable component and the column has `enableSorting: true` (or omit it for default behavior).
**Q: Filters not showing?**
A: Ensure your column has a `filterConfig` property. Display columns don't have filtering by design.
**Q: TypeScript errors?**
A: Make sure your data type matches the generic parameter in `generateColumns()`.
**Q: Pagination not working?**
A: Check that `enablePagination={true}` is set on the SuperTable component.
## 📄 License
MIT License - feel free to use in your projects!
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
---
Built with ❤️ using React, TypeScript, TanStack Table, and shadcn/ui.