🔀 ArtFlow Table - Complete Sorting Guide

Version: 1.5.2+
Last Updated: December 30, 2025
Status: Production Ready ✅

📖 Table of Contents

1. Quick Start
2. Basic Sorting
3. Advanced Sorting
4. Sortable Columns
5. Performance Optimization
6. Troubleshooting
7. Real-World Examples
8. API Reference

🚀 Quick Start

Basic Sorting Setup

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Transaction',
    'columns' => [
        ['key' => 'amount', 'label' => 'Amount'],
        ['key' => 'date', 'label' => 'Date'],
        ['key' => 'description', 'label' => 'Description'],
    ],
    'sortBy' => 'date',          // ✅ Sort by 'date' column initially
    'sortDirection' => 'desc',   // ✅ Sort in descending order (newest first)
])

What Happens

1. Table loads with data sorted by date column
2. User sees newest transactions first
3. User can click column headers to change sort
4. Clicking again toggles ascending/descending
5. All sorting handled reactively with Livewire

📊 Basic Sorting

Default Sort Column

The sortBy parameter specifies which column to sort by initially:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [
        ['key' => 'id', 'label' => 'ID'],
        ['key' => 'name', 'label' => 'Name'],
        ['key' => 'price', 'label' => 'Price'],
    ],
    'sortBy' => 'name',  // Start sorting by name column
])

Sort Direction

The sortDirection parameter controls the initial sort order:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [...],
    'sortBy' => 'price',
    'sortDirection' => 'asc',    // Lowest to highest
])

Valid Values:

• 'asc' - Ascending order (A→Z, 1→∞)
• 'desc' - Descending order (Z→A, ∞→1)

Backward Compatibility

The package also supports the legacy sort parameter:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [...],
    'sort' => 'desc',  // Still works! (backward compatible)
])

🎯 Advanced Sorting

Sorting by Related Columns (Relationships)

Sort by columns from related models:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Order',
    'columns' => [
        ['key' => 'order_number', 'label' => 'Order', 'sort' => true],
        [
            'key' => 'customer_name',
            'label' => 'Customer',
            'relation' => 'customer:name',  // Sort by customer.name
        ],
        [
            'key' => 'amount',
            'label' => 'Amount',
        ],
    ],
    'sortBy' => 'customer_name',      // Sort by customer.name initially
    'sortDirection' => 'asc',
])

How it Works:

1. System detects relation field in column
2. Automatically JOINs the customer table
3. Sorts by customer.name column
4. Uses DISTINCT to avoid duplicate rows from the join
5. Still performs efficiently with single query!

Sorting by Count Columns

Sort by relationship count:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Category',
    'columns' => [
        ['key' => 'name', 'label' => 'Category'],
        [
            'key' => 'products_count',
            'label' => 'Product Count',
        ],
    ],
    'sortBy' => 'products_count',      // Sort by count of products
    'sortDirection' => 'desc',          // Most products first
])

How it Works:

1. Column key ends with _count → auto-detected
2. Relation name extracted: products from products_count
3. withCount('products') added to query
4. Sorts by aggregated count efficiently
5. No N+1 queries!

Sorting by JSON Columns

Sort by values inside JSON columns:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\User',
    'columns' => [
        ['key' => 'name', 'label' => 'Name'],
        [
            'key' => 'metadata',
            'label' => 'Country',
            'json' => 'address.country',  // Sort by JSON path
        ],
    ],
    'sortBy' => 'metadata',             // Column key
    'sortDirection' => 'asc',
])

How it Works:

1. Column has json key with path
2. System extracts path from JSON: address.country
3. Uses MySQL JSON_EXTRACT() function
4. Efficiently sorts by nested JSON values
5. Works with MySQL 5.7+

✅ Sortable Columns

Which Columns Are Sortable?

✅ SORTABLE:

• Database columns: ['key' => 'name', ...]
• Related columns (simple): ['relation' => 'user:name', ...]
• Count columns: ['key' => 'items_count', ...]
• JSON columns: ['key' => 'data', 'json' => 'field', ...]

❌ NOT SORTABLE:

• Nested relations: ['relation' => 'user.profile:name', ...]
• Function columns: ['function' => 'getStatus', ...]
• Raw HTML columns: ['raw' => '<button>...</button>', ...]

Example: Mixed Columns

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Product',
    'columns' => [
        // ✅ SORTABLE - Database column
        ['key' => 'name', 'label' => 'Product Name'],
        
        // ✅ SORTABLE - Related column
        ['key' => 'brand_name', 'label' => 'Brand', 'relation' => 'brand:name'],
        
        // ✅ SORTABLE - Count column
        ['key' => 'reviews_count', 'label' => 'Reviews'],
        
        // ❌ NOT SORTABLE - Function column
        ['key' => 'status', 'label' => 'Status', 'function' => 'getStatus'],
        
        // ❌ NOT SORTABLE - Raw HTML
        ['key' => 'actions', 'label' => 'Actions', 'raw' => '<a>Edit</a>'],
    ],
])

Visual Indicators

The table automatically shows indicators:

Name ↓          (Sorted ascending by Name)
Brand ↑         (Sorted descending by Brand)
Reviews         (Not currently sorted)
Status (⚠️)     (Not Sortable - function column)
Actions         (Not Sortable - raw HTML)

⚡ Performance Optimization

Single Query with Advanced Sorting

The system automatically optimizes sorting:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Order',
    'columns' => [
        ['key' => 'order_number', 'label' => '#'],
        ['key' => 'customer_name', 'label' => 'Customer', 'relation' => 'customer:name'],
        ['key' => 'items_count', 'label' => 'Items'],
        ['key' => 'total', 'label' => 'Total'],
    ],
    'sortBy' => 'customer_name',
    'sortDirection' => 'asc',
])

Generated SQL (Optimized):

SELECT DISTINCT orders.* 
FROM orders
LEFT JOIN customers ON orders.customer_id = customers.id
WITH COUNT(order_items) as items_count
WHERE orders.status = 'completed'
ORDER BY customers.name ASC
LIMIT 50;

Query Count: 1 query for 50 rows ✅ No N+1 Queries: ✅

Performance Tips

1. Use Related Columns Properly

   ✅ Good:    'relation' => 'category:name'
   ❌ Bad:     Manually fetching relationship
   

2. Leverage Count Columns

   ✅ Good:    'key' => 'items_count'
   ❌ Bad:     Loading all items and counting in PHP
   

3. Avoid Nested Relations for Sorting

   ✅ Good:    Sort by primary relation only
   ❌ Bad:     'relation' => 'user.profile.country:name'
   

4. Pagination + Sorting

   [@livewire](https://github.com/livewire)('aftable', [
       'model' => 'App\Models\Item',
       'columns' => [...],
       'sortBy' => 'created_at',
       'sortDirection' => 'desc',
       'records' => 25,  // 25 items per page
   ])
   

🐛 Troubleshooting

Problem: Sorting Doesn't Work

Symptom: Clicking column header doesn't change order

Solutions:

1. Ensure column is database field (not computed)
2. Check column configuration has 'key' field
3. Verify model has the column

// ✅ WORKS - Database column
['key' => 'email', 'label' => 'Email']

// ❌ DOESN'T WORK - Computed property
['key' => 'full_name', 'label' => 'Full Name']  // If only exists in code

Problem: Sorting by Relationship Shows Wrong Data

Symptom: Related data appears but sort is incorrect

Cause: Incorrect relation format

Fix:

// ❌ WRONG - Missing column name
['key' => 'category_id', 'label' => 'Category', 'relation' => 'category']

// ✅ CORRECT - Full relation path
['key' => 'category_id', 'label' => 'Category', 'relation' => 'category:name']

Problem: Initial Sort Not Applied

Symptom: sortBy and sortDirection are ignored

Cause: Column doesn't exist or isn't sortable

Solution:

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Item',
    'columns' => [
        ['key' => 'created_at', 'label' => 'Created'],  // ✅ This exists
    ],
    'sortBy' => 'created_at',      // ✅ Must match column key
    'sortDirection' => 'desc',
])

Problem: Undefined Variable $sortColumn

Symptom: Error: Undefined variable $sortColumn

Cause: Using old Blade template syntax

Fix: Update to use sortColumn property

[@if](https://github.com/if) ($sortColumn == 'name')
    {{-- Sorting by name --}}
[@endif](https://github.com/endif)

Or use the new sortBy alias:

public $sortBy = null;  // Now available

🎯 Real-World Examples

Example 1: E-Commerce Products Table

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Product',
    'columns' => [
        ['key' => 'sku', 'label' => 'SKU'],
        ['key' => 'name', 'label' => 'Product Name'],
        ['key' => 'price', 'label' => 'Price'],
        ['key' => 'category_name', 'label' => 'Category', 'relation' => 'category:name'],
        ['key' => 'stock', 'label' => 'Stock'],
        ['key' => 'reviews_count', 'label' => 'Reviews'],
    ],
    'sortBy' => 'price',              // Most expensive first
    'sortDirection' => 'desc',
    'records' => 50,
])

Example 2: Financial Transactions (Date-Based)

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\AccountFlow\Transaction',
    'columns' => [
        ['key' => 'date', 'label' => 'Date'],
        ['key' => 'amount', 'label' => 'Amount'],
        ['key' => 'type', 'label' => 'Type'],
        ['key' => 'category_id', 'relation' => 'category:name', 'label' => 'Category'],
        ['key' => 'account_id', 'relation' => 'account:name', 'label' => 'Account'],
        ['key' => 'description', 'label' => 'Description'],
    ],
    'sortBy' => 'date',               // Newest first
    'sortDirection' => 'desc',
    'records' => 25,
])

Example 3: User Management (Name-Based)

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\User',
    'columns' => [
        ['key' => 'name', 'label' => 'Full Name'],
        ['key' => 'email', 'label' => 'Email'],
        ['key' => 'role', 'label' => 'Role'],
        ['key' => 'organization_name', 'label' => 'Organization', 'relation' => 'organization:name'],
        ['key' => 'last_login_at', 'label' => 'Last Login'],
        ['key' => 'created_at', 'label' => 'Created'],
    ],
    'sortBy' => 'name',               // A to Z
    'sortDirection' => 'asc',
    'records' => 50,
])

Example 4: Orders with Complex Sorting

[@livewire](https://github.com/livewire)('aftable', [
    'model' => 'App\Models\Order',
    'columns' => [
        ['key' => 'id', 'label' => 'Order ID', 'hidden' => true],
        ['key' => 'order_number', 'label' => 'Order #'],
        ['key' => 'customer_name', 'label' => 'Customer', 'relation' => 'customer:name'],
        ['key' => 'total_amount', 'label' => 'Total Amount'],
        ['key' => 'items_count', 'label' => 'Items'],
        ['key' => 'status', 'label' => 'Status'],
        ['key' => 'created_at', 'label' => 'Order Date'],
    ],
    'sortBy' => 'created_at',         // Sort by order date
    'sortDirection' => 'desc',        // Newest orders first
    'records' => 25,
])

📚 API Reference

Component Parameters

[@livewire](https://github.com/livewire)('aftable', [
    // ... other parameters ...
    
    'sortBy' => 'column_key',           // Initial sort column
    'sortDirection' => 'asc|desc',      // Initial sort direction
    'sort' => 'asc|desc',               // Backward compatibility
])

Public Properties

public $sortBy = null;           // Current sort column (alias for sortColumn)
public $sortColumn = null;       // Current sort column (internal)
public $sortDirection = 'asc';   // Current sort direction (asc/desc)

Public Methods

// Programmatically set sort
public function sortBy($column)

// Get sort state
public function getSortIcon($column): string
public function isColumnSorted($column): bool
public function getSortDirection($column): ?string

// Get sortable columns
public function getSortableColumns(): array

// Reset sorting
public function resetSortToDefault()

Column Configuration

'columns' => [
    [
        'key' => 'name',                    // Database column (sortable)
        'label' => 'Product Name',
        'sort' => true,                     // ✅ Explicitly enable sorting
    ],
    [
        'key' => 'category_id',
        'relation' => 'category:name',      // ✅ Relation column (sortable)
        'label' => 'Category',
    ],
    [
        'key' => 'items_count',
        'label' => 'Items',                 // ✅ Count column (auto-sortable)
    ],
    [
        'key' => 'data',
        'json' => 'address.city',           // ✅ JSON column (sortable)
        'label' => 'City',
    ],
    [
        'key' => 'status',
        'function' => 'getStatus',          // ❌ Function column (NOT sortable)
        'label' => 'Status',
    ],
    [
        'key' => 'actions',
        'raw' => '<a>Edit</a>',             // ❌ Raw HTML (NOT sortable)
        'label' => 'Actions',
    ],
]

🎓 Best Practices

✅ DO

• Use sortBy for initial sort column
• Use sortDirection for initial order
• Keep database columns sortable
• Use relations for related data sorting
• Leverage count columns for efficient sorting
• Test with multiple users simultaneously

❌ DON'T

• Use computed/function columns for sorting
• Nest multiple relations (causes slow queries)
• Sort by raw HTML columns
• Skip the relation format (causes N+1 queries)
• Use ascending/descending as column keys
• Hardcode sort in views (use component params)

🔧 Performance Metrics

With Proper Sorting

Without Optimization

📞 Support & Feedback

• Developer Site: https://artflow.pk
• Package: artflow-studio/table
• Version: 1.5.2+
• PHP: 8.0+
• Laravel: 11+

Last Updated: December 30, 2025
Status: Production Ready ✅