Built‑in DataTables stateSave versus external URL query strings for paging state during Ajax migration

Answer to the Core Question

Enabling stateSave:true together with serverSide:true does keep the current paging, sorting, and filter state across full page reloads as long as the Ajax URL and the table’s id remain unchanged. The state is stored in localStorage keyed by the Ajax URL, so a change to that URL clears the stored snapshot. When the table is re‑initialised, DataTables reads the stored values and applies them to the next Ajax request. This behaviour is consistent in DataTables 1.13 and earlier releases, but the documentation notes that stateSave was originally designed for client‑side tables and may require custom handling in server‑side mode.

Why It Works (and Where It Can Fail)

• State is stored as a JSON object containing start, length, order, search, etc.
• On initialisation, DataTables merges the stored state with the current configuration.
• If the Ajax URL changes, the key in localStorage changes and the stored snapshot is not found, so the table falls back to defaults.
• In server‑side mode, the stored start and length are sent to the server as start and length unless they are remapped via stateSaveParams.

Adjusting with stateSaveParams

When your server expects different parameter names (e.g., offset and limit), you can map the stored values like this:

$('#example').DataTable({
    serverSide: true,
    ajax: {
        url: '/api/items',
        data: function(d) {
            // d already contains start/length from DataTables
            d.offset = d.start;
            d.limit  = d.length;
            delete d.start;
            delete d.length;
        }
    },
    stateSave: true,
    stateSaveParams: function(settings, data) {
        // Ensure the stored values use the names your server expects
        data.offset = data.start;
        data.limit  = data.length;
        delete data.start;
        delete data.length;
    }
});

This guarantees that the server receives the correct paging values even if the Ajax URL changes (e.g., you add a query string to switch between legacy and new endpoints). The key point is that stateSaveParams runs after DataTables has merged the stored state, so you can rename or transform it before it is sent.

External URL‑Query‑String Approach

Encoding paging, sorting, and filter state directly in the query string (e.g., ?page=3&size=25&sort=name,asc) has several advantages:

• It is independent of DataTables internals and works uniformly across all releases.
• Links become shareable and bookmarkable, which is useful for debugging or user navigation.
• It avoids reliance on localStorage, so it works in incognito mode or when storage is disabled.
• When the Ajax URL changes, you can simply read the new parameters and initialise the table accordingly.

The trade‑off is that you need to implement the parsing logic yourself and ensure sensitive parameters are not exposed unintentionally. For most incremental migrations, however, this method is simpler and more transparent.

Recommended Migration Path

1. Keep the Ajax URL stable during the migration. Use stateSave:true with optional stateSaveParams mapping if your server expects non‑standard parameter names.
2. Test the persistence by navigating to a non‑first page, reloading the page, and verifying that the same page appears.
3. If you must change the Ajax endpoint (e.g., switching from /api/items to /api/items?new=true), either:
   • Use stateSaveParams to remap stored values to the new endpoint’s parameters, or
   • Switch to the URL‑query‑string approach and read those values on initialisation.
4. Consider adding a fallback: on initial load, check localStorage for a stored state and merge it with the URL parameters if both exist.

Missing Diagnostic Detail

To finalize the recommendation, could you confirm:

• Whether the Ajax URL will change during the migration or remains constant?
• Which DataTables version you are targeting?

These details influence whether the built‑in stateSave can be relied upon or if a URL‑based solution is safer.