custom_cursor/README.md

custom_cursor

Custom cursor decoding, registration, and display for Flutter apps.

custom_cursor decodes Windows .cur and .ani resources, Linux Xcursor themes, native raster images (PNG/GIF/APNG/WebP/JPEG/BMP), and static SVG into [Cursor] / [AnimatedCursor] models. A [CursorRegion] widget switches the platform cursor when the mouse hovers its subtree, honoring the OS pointer-size multiplier and mirroring cursors for right-to-left layouts.

Platforms

Platform	Support	Implementation
macOS	✅	Swift Package Manager
Windows	✅	C++ (GDI+)
Linux	✅	C++ (GTK3)
Web	✅	CSS cursor: url(...)
Android	✅	Kotlin (API 24+)

Linux prerequisites

Building on Linux requires GTK3 development headers:

sudo apt-get install -y libgtk-3-dev

Cursor size limit

Cursors are capped at 128 px per dimension, matching browser and native system limits. Custom sizes larger than 128 are clamped automatically ([CursorScaler]). 128 is available as a preset alongside the standard sizes.

Android

Android support requires a minimum SDK of 24 (the pointer-icon API is gated behind Build.VERSION.SDK_INT >= N; on older devices the system arrow is kept).

Usage

import "package:custom_cursor/custom_cursor.dart";

final cursors = cursorAssets({
  "normal": await decodeCursorAsset(curBytes, ...),
  ...
});

// Register and display the "normal" cursor while hovering [child].
CursorRegion(
  cursors: cursors,
  child: child,
)

Registered cursors use the "custom_cursor" method channel and follow the OS pointer-size multiplier through systemCursorScale / registerScaleObserver, and the OS layout direction through systemDirection / registerDirectionObserver.