[Bug] Fix meaning of control vs control action

[petar-qb]

closes https://github.com/McK-Internal/vizro-internal/issues/2421

Description

This PR introduces a clear distinction between vm.Filter and filter_action (same for parameter). What does it mean?

Here's the configuration of the vm.Filter from scratch_dev/app.py:

        vm.Filter(
            column="species",
            targets=["p11_graph"],
            selector=vm.RadioItems(
                title="Filter that does NOT auto-apply, but is taken into account when its target Graph is updated.",
                actions=vm.Action(function=capture("action")(lambda _trigger: _trigger)(), outputs="p11_text"),
            )
        )

On the main branch, overwriting vm.Filter.selector.actions causes the filter to stop filtering, which is incorrect. vm.Filter is meant to represent filtering logic, and it should always be applied whenever its targets are refreshed (via OPL or any other action), regardless of whether the selector’s actions are overwritten.

So, the vm.Filter.selector.actions defines of what happens when the filter’s trigger property changes, as with any other model. For vm.Filter, the default behaviour is to refresh the targeted figures (it's just a default behaviour). If actions are overwritten, the custom behaviour should run instead. However, the filtering must still be applied when the target figures are refreshed.

Also, this PR prepares the ground for replacing the private _filter_action with the new public update_figures API by clarifying responsibilities and reducing ambiguity in the filtering model.

Screen recording from the main:

❌ vm.Filter is NOT taken into account when p11_graph is updated from on_page_load or parameter_action.

Screen.Recording.2026-01-08.at.14.13.43.mov

Screen recording from the bug/fix_meaning_of_control_vs_control_action:

✅ vm.Filter is taken into account when p11_graph is updated from on_page_load or parameter_action.

Screen.Recording.2026-01-08.at.14.15.03.mov

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[github-actions]

View the example dashboards of the current commit live on PyCafe ☕ 🚀

Updated on: 2026-01-09 09:40:23 UTC
Commit: 5d24c4a

Compare the examples using the commit's wheel file vs the latest released version:

vizro-core/examples/scratch_dev

View with commit's wheel vs View with latest release

vizro-core/examples/dev/

View with commit's wheel vs View with latest release

vizro-core/examples/visual-vocabulary/

View with commit's wheel vs View with latest release

vizro-core/examples/tutorial/

View with commit's wheel vs View with latest release

[Copilot]

Pull request overview

This PR fixes a bug where vm.Filter stops filtering when its selector's actions are overwritten. The fix separates the filter's internal filtering logic from the selector's action behavior by storing the filter function directly on the Filter model as a private attribute _filter_function.

Key Changes:

• Adds _filter_function private attribute to Filter model to store the filtering logic independently of selector actions
• Refactors _apply_filter_controls and _get_parametrized_config to use new get_selector_parent_control utility
• Updates scratch_dev test app to demonstrate the fixed behavior

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vizro-core/src/vizro/models/_controls/filter.py	Adds _filter_function private attribute and refactors pre_build to always set it, regardless of whether selector actions are overwritten
vizro-core/src/vizro/models/_controls/_controls_utils.py	Adds get_selector_parent_control utility function to retrieve parent control (Filter or Parameter) from a selector
vizro-core/src/vizro/actions/_actions_utils.py	Refactors _apply_filter_controls and _get_parametrized_config to use get_selector_parent_control and access filter function from Filter model
vizro-core/examples/scratch_dev/app.py	Updates test app to demonstrate the bug fix with filter behavior
vizro-core/changelog.d/20260108_150147_petar_pejovic_fix_meaning_of_control_vs_control_action.md	Adds empty changelog template (needs to be filled out)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[huong-li-nguyen]

I might be missing a bit of context, but based on the PR description I thought the behaviour is now: Custom action will be appended to the default action of filtering for the Filter for example.

Based on that understanding, i would have thought that the Filter would apply automatically with the custom action added on top. However, in the scratch app, the filtering is only applied after the parameter action is also applied, so it's not the behaviour I would have expected 🤔

Is this intended? What I would have expected is that the filter is ALWAYS filtering and then adding any custom action on top. So in the scratch dev app, I would have expected it to filter regardless whether i click on the parameter action or not.

[huong-li-nguyen]

Suggested change

	- Fix that `Filter` and `Parameter` logic is always applied on target figure refresh, even if custom selector actions are defined. ([#1537](https://github.com/mckinsey/vizro/pull/1537))
	- Custom actions for `Filters` and `Parameters` now run in addition to the default behavior, rather than replacing it. Filtering and parameter updates will always be applied as expected. ([#1537](https://github.com/mckinsey/vizro/pull/1537))

[huong-li-nguyen]

Do we need to add some tests for this?

[antonymilne]

Just a note to say that I've seen this PR and #1538. I'm going to think through both of them properly next week as well as finally go back to my notes to find the answers to these questions you asked:

• could you check is there a reason you haven't made the filter_action public?
• could you find your notes about syncing/cascading controls?

I spent a looooong time last year thinking about about implementing something very similar to #1538 and ultimately decided not to. Possibly that was the wrong decision, but I'd like to go back and find my earlier thoughts on it to understand what I was thinking before anyway!