diff --git a/docs/resources/ui/widgets/built-in-widgets/imgs/mouse-region-events.svg b/docs/resources/ui/widgets/built-in-widgets/imgs/mouse-region-events.svg new file mode 100644 index 00000000..1ebd7c48 --- /dev/null +++ b/docs/resources/ui/widgets/built-in-widgets/imgs/mouse-region-events.svg @@ -0,0 +1,49 @@ + + How MouseRegion pointer events work + A pointer moves into the area occupied by a MouseRegion child and triggers On Mouse Enter. When the pointer leaves, On Mouse Exit runs. + + + MouseRegion pointer events + The child widget defines the active hover area + + + Pointer input + + + MOVES IN OR OUT + + + + + + + + MouseRegion + + + ACTIVE HOVER AREA + + Child widget + The region follows the child's size + + + + + + + + + + On Mouse Enter + Pointer enters the region + + SHOW OR START + + + + + On Mouse Exit + Pointer leaves the region + + HIDE OR RESET + diff --git a/docs/resources/ui/widgets/built-in-widgets/mouse-region.md b/docs/resources/ui/widgets/built-in-widgets/mouse-region.md index 22ea735a..b4f71850 100644 --- a/docs/resources/ui/widgets/built-in-widgets/mouse-region.md +++ b/docs/resources/ui/widgets/built-in-widgets/mouse-region.md @@ -1,38 +1,32 @@ --- -title: Mouse Region +title: MouseRegion slug: mouse-region tags: [Base Elements] +keywords: [MouseRegion, Hover, Mouse Enter, Mouse Exit, Cursor, Widget] +description: Learn how to respond to pointer hover events with the MouseRegion widget in FlutterFlow. --- # MouseRegion -The `MouseRegion` widget lets you know whenever the mouse pointer enters or exits from a widget. You could use it to build a user experience (UX), such as animating buttons when a user hovers over them and revealing or hiding menu items when a user hovers over the menu icon. +The **MouseRegion** widget detects when a mouse pointer enters or leaves the area occupied by its child. You can use these events to start an animation, show additional content, or update another part of the interface while the pointer is hovering. -On this page, you will learn how to [add the MouseRegion widget](#adding-mouseregion-widget), use it to [show/hide elements](#showhide-elements-using-mouseregion), and [customize](#customizing) it. - -## Adding MouseRegion widget +:::info +MouseRegion interactions are designed for web and desktop apps used with a mouse or a trackpad. Provide a tap-based alternative for touch devices, and do not make essential actions available only on hover. +::: -Here are the step-by-step instructions to build such an example: +![A pointer enters a MouseRegion and triggers On Mouse Enter, then leaves and triggers On Mouse Exit.](imgs/mouse-region-events.svg) -1. First, click on the **+ Add Widget** and drag the **MouseRegion** widget from the **Base -Elements** tab or add it directly from the widget tree. -2. Add a [**Button**](../basic-widgets/button.md) (inside MouseRegion) - with [**On Action Trigger**](../../../../ff-concepts/animations/widget_animations.md#animation-on-action-trigger) animation. -3. Select the **MouseRegion** widget, select **Actions** from the Properties Panel (the right menu), and click **Open**. This will open an **Action flow Editor** in a new popup window. -4. Select the **On Mouse Enter** tab. Actions added under this will be triggered whenever the mouse enters the MouseRegion widget. - 1. Add the [Widget Animation](../../../../ff-concepts/animations/widget_animations.md) action to start the animation on a Button. -5. Select the **On Mouse Exit** tab. Actions added under this will be triggered whenever the mouse leaves the MouseRegion widget. - 1. Add the [Widget Animation](../../../../ff-concepts/animations/widget_animations.md) action to stop the animation on a Button. +The following preview shows how a widget can respond when the pointer enters and leaves its MouseRegion:
-
-

+## MouseRegion Events -Here are the step-by-step instructions: +The following events are available from the MouseRegion widget's **Actions** tab: -1. First, add the Stack **>** **Container** **> MouseRegion >** **IconButton** to display the menu -icon. -2. Add the **Container > MouseRegion >** **Column** (with some menu items/options) inside the same Stack widget. +### On Mouse Enter -:::info[Note] -Note that we wrapped the menu icon and its options inside the MouseRegion widget. In -the next step, we will add the same actions for both MouseRegion widgets so that the menu options stay visible as long as you hover over them. -::: +**On Mouse Enter** runs when the pointer moves into the MouseRegion. Use it to show content, start a [widget animation](../../../../ff-concepts/animations/widget_animations.md#animation-on-action-trigger), or update a state variable. -![img_9.png](imgs/img_9.png) +### On Mouse Exit -3. Create a boolean [App State variable](../../../../resources/data-representation/app-state.md) - and use it -to -[add conditional visibility](../../widgets/widget-commonalities.md#conditional) - on menu options. -4. On both MouseRegion widgets, add an [update app state variable](../../../../resources/data-representation/app-state.md#update-app-state-action) action to set **True** when the mouse enters and **False** when the mouse exit. +**On Mouse Exit** runs when the pointer leaves the MouseRegion. Use it to hide content, stop or reverse an animation, or reset a state variable. -
-
- -
-
Use app state variable and MouseRegion to show/hide a widget
-
+## Customizing +Select the **MouseRegion** widget and open **MouseRegion Properties** in the [Properties Panel](../../../../intro/ff-ui/builder.md#properties-panel). -## Customizing +### Changing the Mouse Cursor -You can customize the appearance and behavior of this widget using the various properties -available under the **Properties Panel**. +Use **Mouse Cursor** to choose the cursor style shown while the pointer is inside the MouseRegion. -### Customize mouse cursor +When the child is clickable, choose a cursor that communicates that interaction. A suitable cursor helps users understand what they can do before they interact. -When a mouse enters the widget, its cursor will change to the appropriate one by default. However, you can also set it to a custom one if you wish to. +### Controlling Overlapping MouseRegions -To customize the mouse cursor, select the **MouseRegion** widget, move to the properties panel, find the **Mouse Cursor** dropdown select the one you think fits best. +Enable **Opaque** when this MouseRegion should prevent MouseRegion widgets behind it from responding to the pointer. This is useful when MouseRegions overlap, such as inside a Stack, and only the region in front should receive hover events. -
- -
+Disable **Opaque** when MouseRegion widgets behind it should remain responsive to the pointer. + +#### Example: Icon Over a Hoverable Card + +Suppose a Stack contains a product card that changes elevation on hover and a favorite icon positioned over the card. Both widgets have their own MouseRegion. + +- Enable **Opaque** on the favorite icon's MouseRegion when hovering over the icon should show its tooltip without also changing the card's elevation. +- Disable **Opaque** when hovering over the favorite icon should trigger both the icon and card hover effects. + +## Best Practices +- Treat hover as an enhancement and provide a tap-based alternative for touch devices. +- Keep essential actions and information accessible without requiring hover. +- Keep the MouseRegion's size stable while the pointer is inside it to prevent repeated enter and exit events. +- Choose a cursor that accurately communicates the interaction. +- Test the hover interaction with a mouse and a trackpad. Separately test the tap and keyboard alternatives provided for users who cannot use hover.