# 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:

```sh
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

```dart
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`.