Skip to content
Blog

Building Desktop and Web Interactions with MouseRegion in Flutter

Explore MouseRegion in Flutter for tracking mouse pointers, handling enter/exit hover events, and updating system mouse cursors on Web and Desktop platforms.

Published on • November 9, 2026

AI Assistant

Hover states, mouse pointer tracking, and custom cursor indicators are fundamental to building web and desktop applications. In Flutter, the MouseRegion widget provides fine-grained control over pointer interactions whenever a physical mouse or trackpad is used.

What is MouseRegion?

MouseRegion is a widget that tracks the movement of a mouse pointer within its boundaries. It fires events when the pointer enters the region, moves inside it, or exits the region. It also controls the SystemMouseCursor displayed while hovering over the target region.

import 'package:flutter/material.dart';

class HoverCard extends StatefulWidget {
  const HoverCard({super.key});

  @override
  State<HoverCard> createState() => _HoverCardState();
}

class _HoverCardState extends State<HoverCard> {
  bool _isHovered = false;

  @override
  Widget build(BuildContext context) {
    return MouseRegion(
      cursor: SystemMouseCursors.click,
      onEnter: (event) {
        setState(() => _isHovered = true);
      },
      onExit: (event) {
        setState(() => _isHovered = false);
      },
      child: AnimatedContainer(
        duration: const Duration(milliseconds: 200),
        padding: const EdgeInsets.all(24.0),
        decoration: BoxDecoration(
          color: _isHovered ? Colors.blue.shade50 : Colors.white,
          borderRadius: BorderRadius.circular(12),
          boxShadow: [
            BoxShadow(
              color: _isHovered ? Colors.black26 : Colors.black12,
              blurRadius: _isHovered ? 12 : 4,
              offset: Offset(0, _isHovered ? 6 : 2),
            ),
          ],
        ),
        child: Text(
          _isHovered ? 'Pointer Hovering!' : 'Hover Over Me',
          style: TextStyle(
            color: _isHovered ? Colors.blue.shade900 : Colors.black87,
            fontWeight: FontWeight.bold,
          ),
        ),
      ),
    );
  }
}

System Mouse Cursors

Flutter provides built-in system mouse cursors through SystemMouseCursors. These map directly to native operating system cursors:

  • SystemMouseCursors.click: Pointer hand cursor for buttons and links.
  • SystemMouseCursors.text: I-beam text selection cursor.
  • SystemMouseCursors.forbidden: Slash-circle forbidden cursor.
  • SystemMouseCursors.grab & SystemMouseCursors.grabbing: Open and closed hand cursors for draggable surfaces.
  • SystemMouseCursors.resizeColumn & SystemMouseCursors.resizeRow: Splitter resizing arrows.
MouseRegion(
  cursor: SystemMouseCursors.grab,
  child: Container(
    padding: const EdgeInsets.all(16),
    color: Colors.amber.shade100,
    child: const Text('Draggable Handle'),
  ),
)

Precise Tracking with onHover

While onEnter and onExit inform you when the pointer crosses the boundary, onHover delivers continuous PointerHoverEvent updates containing local and global pointer coordinates.

class CoordinatesTracker extends StatefulWidget {
  const CoordinatesTracker({super.key});

  @override
  State<CoordinatesTracker> createState() => _CoordinatesTrackerState();
}

class _CoordinatesTrackerState extends State<CoordinatesTracker> {
  Offset _localPos = Offset.zero;

  @override
  Widget build(BuildContext context) {
    return MouseRegion(
      onHover: (event) {
        setState(() {
          _localPos = event.localPosition;
        });
      },
      child: Container(
        height: 200,
        color: Colors.grey.shade200,
        alignment: Alignment.center,
        child: Text(
          'X: ${_localPos.dx.toStringAsFixed(1)}, Y: ${_localPos.dy.toStringAsFixed(1)}',
          style: const TextStyle(fontSize: 16, fontFamily: 'monospace'),
        ),
      ),
    );
  }
}

Performance Tip: HitTestBehavior

MouseRegion accepts a hitTestBehavior property:

  • HitTestBehavior.deferToChild: Listens to events only where child widgets handle hit tests.
  • HitTestBehavior.opaque: Captures pointer events over the entire bounds of the region, regardless of transparent child background.
  • HitTestBehavior.translucent: Allows background widgets beneath transparent areas to receive mouse events simultaneously.

Takeaway: MouseRegion is an essential building block for adding desktop desktop/web polish, interactive feedback, and proper cursor iconography to cross-platform Flutter applications.