Active Grid

State Persistence - Active Grid

Overview

State persistence saves the grid's state (sorting, filtering, column visibility, etc.) to localStorage. When users return, their preferences are automatically restored.

<ActiveGrid
  gridId="users"
  enablePersistence={true}
  columns={columns}
  data={data}
  {...}
/>

Basic Usage

Enable persistence with a unique gridId:

<ActiveGrid
  gridId="users-grid" // Required for persistence
  enablePersistence={true}
  columns={columns}
  data={data}
  {...}
/>

The gridId prop is required when enablePersistence is true. It serves as the localStorage key.

What Gets Persisted

The following state is automatically saved:

Column visibility - Which columns are shown/hidden
Column order - Order of columns
Column sizing - Width of each column
Column pinning - Which columns are pinned left/right
Sorting - Active sort configuration
Filtering - Applied column filters
Pagination - Current page and page size
Global filter - Search query

Storage Key

State is stored in localStorage with the key:

ActiveGrid-state-{gridId}

For example:

gridId="users" → localStorage key: "ActiveGrid-state-users"

Clearing Persisted State

Programmatically

localStorage.removeItem('ActiveGrid-state-users');

With Reset Button

function UsersTable() {
  const handleReset = () => {
    localStorage.removeItem('ActiveGrid-state-users');
    window.location.reload();
  };
  
  return (
    <>
      <Button onClick={handleReset}>Reset Grid</Button>
      <ActiveGrid
        gridId="users"
        enablePersistence={true}
        {...}
      />
    </>
  );
}

Per-User Persistence

Include user ID in the gridId for per-user state:

Per-View Persistence

Use different gridId values for different views:

Selective Persistence

While you can't selectively disable parts of persistence, you can control initial state:

Migration Strategy

When updating grid configuration, consider versioning:

This creates a new persistence key when the version changes.

Debugging Persistence

View Stored State

Monitor Changes

Complete Example

With Server Mode

Persistence works seamlessly with server mode:

Combining with URL Sync

You can use both persistence and URL sync:

URL parameters take precedence over persisted state.

Browser Compatibility

localStorage is supported in:

Chrome/Edge 4+
Firefox 3.5+
Safari 4+
All modern mobile browsers

Storage Limits

localStorage has a limit of ~5-10 MB per domain. Grid state typically uses:

Simple grid: 1-5 KB
Complex grid: 10-50 KB

Thousands of grids can be stored before hitting limits.

Privacy Considerations

State is stored locally in the user's browser and is not sent to the server. Users can clear it via browser settings.

Clearing All Grid States

To clear all persisted grid states:

Best Practices

✅ DO

Always provide unique gridId
Include user ID for per-user state
Version grids when schema changes
Provide reset functionality
Test with empty localStorage
Document persistence behavior

❌ DON'T

Don't use same gridId for different grids
Don't forget gridId requirement
Don't persist sensitive data
Don't ignore migration needs
Don't assume state exists
Don't rely on persistence alone

State Structure

Example persisted state:

Testing

Test your grid with and without persisted state:

TypeScript

Limitations

Only works with localStorage (not sessionStorage)
Not synced across tabs/windows automatically
Cleared when user clears browser data
Not suitable for sensitive data
Requires manual migration on schema changes

Alternative: Server-Side Persistence

For server-side user preferences:

import { useState } from 'react';
import { ActiveGrid } from '@workspace/active-grid';

function UsersTable() {
  const userId = useAuth().user.id;
  const gridId = `users-${userId}`;
  
  const handleResetGrid = () => {
    if (confirm('Reset all grid preferences?')) {
      localStorage.removeItem(`ActiveGrid-state-${gridId}`);
      window.location.reload();
    }
  };
  
  return (
    <div>
      <div className="mb-4 flex justify-between">
        <h1>Users</h1>
        <Button variant="outline" onClick={handleResetGrid}>
          Reset Grid
        </Button>
      </div>
      
      <ActiveGrid
        gridId={gridId}
        enablePersistence={true}
        columns={columns}
        data={users}
        pagination={{
          enabled: true,
          pageSizeOptions: [10, 25, 50, 100],
        }}
      />
    </div>
  );
}

{
  "columnVisibility": {
    "email": false,
    "phone": false
  },
  "columnOrder": ["name", "status", "createdAt"],
  "columnSizing": {
    "name": 200,
    "status": 120
  },
  "columnPinning": {
    "left": ["name"],
    "right": []
  },
  "sorting": [
    { "id": "createdAt", "desc": true }
  ],
  "columnFilters": [
    { "id": "status", "value": "active" }
  ],
  "globalFilter": "search query",
  "pagination": {
    "pageIndex": 0,
    "pageSize": 25
  }
}

describe('UsersTable', () => {
  beforeEach(() => {
    localStorage.clear();
  });
  
  it('loads with default state', () => {
    render(<UsersTable />);
    // Assert default state
  });
  
  it('restores persisted state', () => {
    localStorage.setItem('ActiveGrid-state-users', JSON.stringify({
      sorting: [{ id: 'name', desc: false }],
    }));
    
    render(<UsersTable />);
    // Assert restored state
  });
});

function UsersTable() {
  const [userPrefs, setUserPrefs] = useState(null);
  
  // Load preferences from server
  useEffect(() => {
    api.getUserPreferences('users-grid').then(setUserPrefs);
  }, []);
  
  // Save preferences to server
  const handleStateChange = (state) => {
    api.saveUserPreferences('users-grid', state);
  };
  
  return (
    <ActiveGrid
      gridId="users"
      state={userPrefs}
      // ... handle state changes
      {...}
    />
  );
}

State Persistence