onColumnOrderChange is called on initial render when using controlled state

[trabati]

material-react-table version

3.2.1

react & react-dom versions

19.2.3

Describe the bug and the steps to reproduce it

When using custom/controlled state management and passing both columnOrder and onColumnOrderChange, the onColumnOrderChange callback is invoked on the initial render.

This behavior appears unintentional and causes issues with state persistence.

Problem description

My goal is to persist the column order only after the user changes it, while still allowing my default column order to evolve over time (e.g., a different default column order later on ).

However, because onColumnOrderChange is called during the initial render, I cannot distinguish between:
• a user-initiated column reorder, and
• the initial state synchronization performed by the table

As a result, the initial render triggers persistence logic and effectively “locks in” the current column order, preventing future updates to the default column order from taking effect.

The expected behavior is that defaults should respect the user’s choice, but only after the user has intentionally changed the column order. Until then, updated defaults should continue to apply.

Expected behavior

onColumnOrderChange should only be called in response to user-driven changes, not during the initial render/state hydration.

—or—

There should be a reliable way to detect whether the change originated from user interaction versus initial setup.

Question

Is this behavior intentional?
If so, what is the recommended way to:
• persist column order only after user interaction, and
• still allow default column order to change over time?

Minimal, Reproducible Example - (Optional, but Recommended)

I’ve created a minimal reproducible example that demonstrates onColumnOrderChange being called on the initial render:

Steps to reproduce:
1. Open the example
2. Reload the preview page and observe the browser console for changeEvent

Observed behavior:
• onColumnOrderChange is called immediately on page load, without any user interaction.
• onColumnVisibilityChange, however, is only called when the user actually changes column visibility, which is the expected behavior.

https://stackblitz.com/edit/github-4tq8jaoq-n9wvvmrt?file=src%2FTS.tsx

Screenshots or Videos (Optional)

onColumnOrderChanged.mov

Do you intend to try to help solve this bug with your own PR?

No, because I do not know how

Terms

• I understand that if my bug cannot be reliably reproduced in a debuggable environment, it will probably not be fixed and this issue may even be closed.