Struct PointerFocusPlugin 

pub struct PointerFocusPlugin;

Available on crate features bevy_input_focus and bevy_picking only.

Plugin which focuses (or blurs) entities in response to pointer clicks.

On a pointer press this hides the focus indicator (InputFocusVisible) and triggers a bubbling AcquireFocus on the clicked entity. That request is then resolved by the focus observers this plugin installs:

• acquire_focus_tab_index focuses the target if it carries a TabIndex, stopping the request, or
• the generalized on_window_acquire_focus_clear observer (installed by InputFocusPlugin) clears focus once the request bubbles up to the window (this is “click outside to unfocus”).

Registering acquire_focus_tab_index here is a temporary bridge: it lets pointer clicks actually acquire focus on focusable targets even when TabNavigationPlugin is not installed (previously that observer only existed inside TabNavigationPlugin, so clicking back into a focusable element without tab navigation could only ever clear focus, never grant it). This re-uses the TabIndex infrastructure until a dedicated, navigation-agnostic pointer-focus target component (a PointerFocusable analog to TabIndex) is designed in a future PR. See https://github.com/bevyengine/bevy/pull/24757.

It is safe to register acquire_focus_tab_index here even when TabNavigationPlugin also registers it: App::add_observer does not deduplicate, so the observer runs twice per request, but it is idempotent — it stops propagation and only mutates InputFocus when the focus target actually changes, so the second run is a no-op.

Because that AcquireFocus event is shared across widgets and focus schemes, be deliberate when changing anything in this pathway — a change here can have engine-wide focus consequences. Individual widgets may also intercept the event and stop its propagation to implement custom behavior (e.g. the number-input scrubber focuses on pointer release rather than press). See the docs on on_window_acquire_focus_clear and acquire_focus_tab_index.

This is intentionally independent of any navigation scheme: it works with tab navigation, directional navigation, or on its own (e.g. an app with only text input). This whole module is gated behind the bevy_picking feature.

Trait Implementations

impl Plugin for PointerFocusPlugin

fn build(&self, app: &mut App)

Configures the App to which this plugin is added.

fn ready(&self, _app: &App) -> bool

Has the plugin finished its setup? This can be useful for plugins that need something asynchronous to happen before they can finish their setup, like the initialization of a renderer. Once the plugin is ready, finish should be called.

fn finish(&self, _app: &mut App)

Finish adding this plugin to the App, once all plugins registered are ready. This can be useful for plugins that depends on another plugin asynchronous setup, like the renderer.

fn cleanup(&self, _app: &mut App)

Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.

fn name(&self) -> &str

Configures a name for the Plugin which is primarily used for checking plugin uniqueness and debugging.

fn is_unique(&self) -> bool

If the plugin can be meaningfully instantiated several times in an App, override this method to return false.