MouseRegion

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.

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.

The following preview shows how a widget can respond when the pointer enters and leaves its MouseRegion:

Adding a MouseRegion Widget

1. Open the Widget Palette and add the MouseRegion widget from Base Elements.
2. Add the widget that should respond to hover as the child of MouseRegion.
3. Set the child's size and position. The MouseRegion covers the area occupied by its child.
4. Select MouseRegion and open the Actions tab to configure its pointer events.

The following walkthrough demonstrates how to add MouseRegion and configure its events:

MouseRegion Events

The following events are available from the MouseRegion widget's Actions tab:

On Mouse Enter

On Mouse Enter runs when the pointer moves into the MouseRegion. Use it to show content, start a widget animation, or update a state variable.

On 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.

Customizing

Select the MouseRegion widget and open MouseRegion Properties in the Properties Panel.

Changing the Mouse Cursor

Use Mouse Cursor to choose the cursor style shown while the pointer is inside the MouseRegion.

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.

Controlling Overlapping MouseRegions

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.