Active Grid

Client Mode - Active Grid

Overview

Client mode loads all data at once and handles sorting, filtering, and pagination entirely in the browser. This is ideal for small to medium datasets where all data can be loaded upfront.

<ActiveGrid
  mode="client"
  data={users}
  columns={columns}
  {...}
/>

When to Use Client Mode

Use Client Mode For:

Datasets under 1,000 rows
Static data that doesn't change frequently
Offline-first applications
Simple use cases without complex filtering
Fast, instant interactions
When server doesn't support pagination/sorting

Use Server Mode For:

Datasets over 1,000 rows
Real-time data that updates frequently
Complex server-side filtering/sorting
Large datasets that would be slow to load
When pagination must be server-side

Basic Usage

type User = {
  id: string;
  name: string;
  email: string;
  status: string;
};

const users: User[] = [
  { id: '1', name: 'John Doe', email: 'john@example.com', status: 'active' },
  { id: '2', name: 'Jane Smith', email: 'jane@example.com', status: 'active' },
  // ... more rows
];

<ActiveGrid
  mode="client"
  data={users}
  columns={columns}
  {...}
/>

Features

All features work automatically in client mode:

Sorting

<ActiveGrid
  mode="client"
  data={users}
  columns={columns}
  // Sorting handled client-side
  {...}
/>

Filtering

<ActiveGrid
  mode="client"
  data={users}
  columns={columns}
  toolbar={{
    search: { placeholder: 'Search...' },
  }}
  // Filtering handled client-side
  {...}
/>

Pagination

<ActiveGrid
  mode="client"
  data={users}
  columns={columns}
  pagination={{
    enabled: true,
    pageSizeOptions: [10, 20, 50],
  }}
  initialPageSize={20}
  // Pagination handled client-side
  {...}
/>

Data Loading

Static Data

const data = [
  { id: '1', name: 'John' },
  { id: '2', name: 'Jane' },
];

<ActiveGrid mode="client" data={data} {...} />

From API

function UsersTable() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    async function loadUsers() {
      const response = await api.getUsers();
      setUsers(response.data);
      setLoading(false);
    }
    loadUsers();
  }, []);
  
  if (loading) return <Spinner />;
  
  return (
    <ActiveGrid
      mode="client"
      data={users}
      columns={columns}
    />
  );
}

With React Query

import { useQuery } from '@tanstack/react-query';

function UsersTable() {
  const { data, isLoading } = useQuery({
    queryKey: ['users'],
    queryFn: () => api.getUsers(),
  });
  
  if (isLoading) return <Spinner />;
  
  return (
    <ActiveGrid
      mode="client"
      data={data?.users || []}
      columns={columns}
    />
  );
}

With SWR

import useSWR from 'swr';

function UsersTable() {
  const { data, error, isLoading } = useSWR('/api/users', fetcher);
  
  if (isLoading) return <Spinner />;
  if (error) return <Error />;
  
  return (
    <ActiveGrid
      mode="client"
      data={data.users}
      columns={columns}
    />
  );
}

Data Updates

Refreshing Data

function UsersTable() {
  const [users, setUsers] = useState<User[]>([]);
  
  const refreshData = async () => {
    const response = await api.getUsers();
    setUsers(response.data);
  };
  
  return (
    <>
      <Button onClick={refreshData}>Refresh</Button>
      <ActiveGrid
        mode="client"
        data={users}
        columns={columns}
      />
    </>
  );
}

Optimistic Updates

function UsersTable() {
  const [users, setUsers] = useState<User[]>(initialUsers);
  
  const handleCommit = async (payload: EditingCommitPayload<User>) => {
    // Optimistically update UI
    setUsers(prev =>
      prev.map(user =>
        user.id === payload.rowId ? payload.newData : user
      )
    );
    
    try {
      await api.updateUser(payload.rowId, payload.changes);
    } catch (error) {
      // Revert on error
      const response = await api.getUsers();
      setUsers(response.data);
    }
  };
  
  return (
    <ActiveGrid
      mode="client"
      data={users}
      columns={columns}
      editMode="cell"
      onDataCommit={handleCommit}
    />
  );
}

Performance Optimization

Memoize Data

const data = useMemo(() => {
  return rawData.map(item => ({
    ...item,
    computed: calculateValue(item),
  }));
}, [rawData]);

<ActiveGrid mode="client" data={data} {...} />

Memoize Columns

const columns = useMemo<GridColumnDef<User>[]>(() => [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
], []);

<ActiveGrid mode="client" columns={columns} {...} />

Virtualization

For larger client-side datasets (1,000+ rows):

Client-Side Filtering

Global Filter

Column Filters

Custom Filter Function

Client-Side Sorting

Default Sorting

Custom Sorting

Complete Example

Performance Limits

Client mode performance degrades with large datasets:

< 500 rows: Excellent performance
500-1,000 rows: Good performance with virtualization
1,000-5,000 rows: Acceptable with virtualization
> 5,000 rows: Consider server mode

Best Practices

✅ DO

Use for small datasets
Memoize data and columns
Enable virtualization for 1,000+ rows
Load all data upfront
Handle loading states
Cache data appropriately

❌ DON'T

Don't use for large datasets
Don't recreate data every render
Don't skip error handling
Don't forget loading states
Don't load data on every render
Don't ignore memory usage

Memory Considerations

Monitor memory usage for large client-side datasets:

TypeScript

const columns: GridColumnDef<User>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    meta: {
      filterType: 'text',
    },
  },
  {
    accessorKey: 'status',
    header: 'Status',
    meta: {
      filterType: 'select',
      filterOptions: [
        { label: 'Active', value: 'active' },
        { label: 'Inactive', value: 'inactive' },
      ],
    },
  },
];

{
  accessorKey: 'tags',
  header: 'Tags',
  filterFn: (row, columnId, filterValue: string[]) => {
    const rowTags = row.getValue(columnId) as string[];
    return filterValue.some(tag => rowTags.includes(tag));
  },
}

{
  accessorKey: 'priority',
  header: 'Priority',
  sortingFn: (rowA, rowB, columnId) => {
    const order = { high: 0, medium: 1, low: 2 };
    return order[rowA.getValue(columnId)] - order[rowB.getValue(columnId)];
  },
}

import { useState, useMemo } from 'react';
import { useQuery } from '@tanstack/react-query';
import { ActiveGrid, GridColumnDef } from '@workspace/active-grid';

type Product = {
  id: string;
  name: string;
  price: number;
  category: string;
  inStock: boolean;
};

function ProductsTable() {
  const { data, isLoading, refetch } = useQuery({
    queryKey: ['products'],
    queryFn: () => api.getProducts(),
  });
  
  const columns = useMemo<GridColumnDef<Product>[]>(() => [
    {
      accessorKey: 'name',
      header: 'Product',
      meta: {
        filterType: 'text',
      },
    },
    {
      accessorKey: 'price',
      header: 'Price',
      meta: {
        cellAlign: 'right',
        valueFormatter: (value) => `$${value.toFixed(2)}`,
        filterType: 'number',
      },
    },
    {
      accessorKey: 'category',
      header: 'Category',
      meta: {
        filterType: 'select',
        filterOptions: [
          { label: 'Electronics', value: 'electronics' },
          { label: 'Clothing', value: 'clothing' },
        ],
      },
    },
    {
      accessorKey: 'inStock',
      header: 'In Stock',
      meta: {
        filterType: 'boolean',
      },
      cell: ({ getValue }) => (getValue() ? '✓' : '✗'),
    },
  ], []);
  
  if (isLoading) {
    return <div>Loading...</div>;
  }
  
  return (
    <ActiveGrid
      mode="client"
      data={data?.products || []}
      columns={columns}
      toolbar={{
        search: {
          placeholder: 'Search products...',
        },
        actions: (
          <Button onClick={() => refetch()}>
            Refresh
          </Button>
        ),
      }}
      pagination={{
        enabled: true,
        pageSizeOptions: [10, 25, 50],
      }}
      initialPageSize={25}
      enableVirtualization={data?.products?.length > 500}
    />
  );
}

Client Mode