Chart.js legend callbacks: unresolved dataset visibility toggle timing

In Chart.js 4.x, the dataset.hidden flag updates AFTER the onClick callback.

The behavior of the legend visibility toggle has changed significantly between version 2.x and the 3.x/4.x releases. This shift determines whether your custom onClick logic sees the state of the dataset before or after the user interaction has been processed.

Version Comparison Summary

• Chart.js 2.x: The internal logic toggles the visibility and updates the dataset.hidden flag before executing the custom onClick callback. Consequently, if you read the flag inside the callback, you are seeing the "post-toggle" state.
• Chart.js 3.x and 4.x: The library executes the custom onClick callback before updating the dataset.hidden flag. Reading the flag within the callback provides the "pre-toggle" state (the state as it existed before the click).

Recommendations for Custom Callbacks

Because of this shift, custom legend logic should be designed based on the specific goal of the state check:

1. To act on the NEW state: In versions 3.x/4.x, you must manually invert the current value of dataset.hidden. If it is false, the user is attempting to hide it.
2. To act on the OLD state: In versions 3.x/4.x, you can read the flag directly, as it still represents the state that is about to change.
3. Cross-version compatibility: If you are maintaining a library that supports both 2.x and 4.x, you must check the Chart version to determine whether to invert the boolean logic within your callback.

Uncertainty and Future Hooks

Chart.js does not currently provide a dedicated hook like beforeVisibilityToggle or afterVisibilityToggle for legend legend. The order of operations is handled within the internal legend-item interaction methods. While there is no official indication of a change in future minor releases, developers should encapsulate visibility logic in helper functions to guard against potential breaking API shifts.

To verify this in your environment, you can use the following snippet:

options: {
  legend: {
    onClick: (event, legendItem, chart) => {
      const dataset = chart.data.datasets[legendItem.index];
      console.log('State during callback:', dataset.hidden);
      // In v4.x, this is the PRE-toggle state
      
      // Call default behavior if you want the toggle to still happen
      // Chart.defaults.legend.onClick(event, legendItem, chart);
    }
  }
}