# flutter_glide

**Repository Path**: wei-echo/flutter_glide

## Basic Information

- **Project Name**: flutter_glide
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flutter_glide

A Flutter image-loading package inspired by **Glide** and **Picasso** from Android.

Automatically detects the image source — network URL, asset path, SVG asset, `file://` URI, or
local file path — and renders it consistently with a single widget API.

---

## Features

| | |
|---|---|
| ✅ Network images | Cached via `cached_network_image`, shimmer while loading |
| ✅ Asset images | PNG / JPG / WebP / GIF via `Image.asset` |
| ✅ SVG assets | Rendered via `flutter_svg` |
| ✅ Local files | Absolute paths **and** `file://` URIs via `Image.file` |
| ✅ Rounded corners | `borderRadius` — applies to every source type |
| ✅ Colour tint | `color` + `colorBlendMode`, applied correctly inside the clip |
| ✅ Tap callbacks | `onTap` on every widget |
| ✅ Memory-cache hints | `maxCacheWidth` / `maxCacheHeight` for network images |
| ✅ Error fallback | Custom `errorWidget` or default broken-image icon |
| ✅ Shimmer placeholder | Customisable colours; also available standalone |
| ✅ Initials avatar | Auto-generated from `name` when image is unavailable |
| ✅ Hero / banner | `GlideBanner` — aspect-ratio image with gradient overlay and caption |
| ✅ Image grid | `GlideGrid` — responsive fixed-column grid |

---

## Widgets

| Widget | Glide equivalent | Description |
|---|---|---|
| `GlideImage` | `Glide.with().load().into()` | Rectangular image — all source types |
| `GlideCircle` | `.circleCrop()` | Circular avatar with initials fallback |
| `GlideBanner` | — | Full-width hero image with gradient overlay & caption |
| `GlideGrid` | — | Responsive multi-column image grid |
| `InitialsAvatar` | — | Standalone initials box (colour + text) |
| `ShimmerPlaceholder` | `.placeholder()` | Standalone shimmer loading box |

---

## Installation

```yaml
dependencies:
  flutter_glide: ^0.1.1
```

```dart
import 'package:flutter_glide/flutter_glide.dart';
```

---

## Usage

### GlideImage — rectangular image

```dart
// Network — cached automatically, shimmer while loading
GlideImage(
  'https://example.com/photo.jpg',
  width: double.infinity,
  height: 200,
)

// Rounded corners
GlideImage(
  'https://example.com/photo.jpg',
  width: double.infinity,
  height: 180,
  borderRadius: BorderRadius.circular(16),
)

// Colour tint (tint is clipped inside borderRadius — no bleed)
GlideImage(
  'https://example.com/photo.jpg',
  width: double.infinity,
  height: 160,
  borderRadius: BorderRadius.circular(12),
  color: Colors.teal.withValues(alpha: 0.4),
  colorBlendMode: BlendMode.multiply,
)

// Tappable
GlideImage(
  'https://example.com/photo.jpg',
  width: double.infinity,
  height: 140,
  onTap: () => Navigator.push(context, ...),
)

// Asset (PNG / JPG / WebP / GIF)
GlideImage('assets/images/banner.png', width: double.infinity, height: 180)

// SVG asset
GlideImage('assets/icons/logo.svg', width: 64, height: 64)

// Local file — absolute path
GlideImage('/data/user/0/com.example.app/cache/photo.jpg', width: 100, height: 100)

// Local file — file:// URI (e.g. from image_picker on iOS)
GlideImage('file:///var/mobile/Containers/.../picked.jpg', width: 100, height: 100)

// Custom placeholder and error widget
GlideImage(
  url,
  placeholder: const Center(child: CircularProgressIndicator()),
  errorWidget: const Icon(Icons.warning, color: Colors.red),
)

// Memory-cache hints — reduces RAM usage for thumbnail lists
GlideImage(
  url,
  width: 80,
  height: 80,
  maxCacheWidth: 160,
  maxCacheHeight: 160,
)

// Custom HTTP headers (auth tokens, etc.)
GlideImage(
  url,
  httpHeaders: {'Authorization': 'Bearer $token'},
)
```

---

### GlideBanner — hero / banner image

```dart
// Basic 16:9 banner
GlideBanner(
  imageUrl: 'https://example.com/hero.jpg',
  aspectRatio: 16 / 9,
)

// Gradient overlay + caption + rounded corners + tap
GlideBanner(
  imageUrl: 'https://example.com/hero.jpg',
  aspectRatio: 16 / 9,
  borderRadius: BorderRadius.circular(14),
  overlayGradient: const LinearGradient(
    begin: Alignment.topCenter,
    end: Alignment.bottomCenter,
    colors: [Colors.transparent, Colors.black54],
  ),
  caption: 'Mountain sunrise, Swiss Alps',
  captionStyle: const TextStyle(color: Colors.white, fontSize: 18, fontWeight: FontWeight.bold),
  onTap: () => Navigator.push(context, ...),
)

// Solid colour overlay
GlideBanner(
  imageUrl: url,
  aspectRatio: 4 / 3,
  overlayColor: Colors.black38,
  caption: 'Breaking news',
)

// Cinematic 21:9
GlideBanner(imageUrl: url, aspectRatio: 21 / 9)
```

---

### GlideGrid — image grid

```dart
// 3-column square grid with tap
GlideGrid(
  imageUrls: [
    'https://example.com/a.jpg',
    'https://example.com/b.jpg',
    'https://example.com/c.jpg',
  ],
  crossAxisCount: 3,
  spacing: 4,
  borderRadius: BorderRadius.circular(8),
  onTap: (index) => print('tapped item $index'),
)

// 2-column landscape grid (4:3 cells)
GlideGrid(
  imageUrls: urls,
  crossAxisCount: 2,
  spacing: 6,
  childAspectRatio: 4 / 3,
  borderRadius: BorderRadius.circular(10),
)

// Custom error widget per cell
GlideGrid(
  imageUrls: urls,
  errorWidget: const Icon(Icons.image_not_supported),
)
```

---

### GlideCircle — circular avatar

```dart
// Network image
GlideCircle(
  imageUrl: 'https://example.com/avatar.jpg',
  radius: 32,
  name: 'Siddharth Rathod',
)

// Empty URL → initials fallback ("SR")
GlideCircle(
  imageUrl: '',
  radius: 40,
  name: 'Siddharth Rathod',
  initialsBackgroundColor: const Color(0xFFD6E9F5),
  initialsTextColor: const Color(0xFF05678D),
)

// Broken URL → falls back to initials
GlideCircle(
  imageUrl: 'https://broken.url/avatar.jpg',
  radius: 40,
  name: 'John Doe',
)

// Border + tap
GlideCircle(
  imageUrl: avatarUrl,
  radius: 28,
  name: 'Ali M',
  borderWidth: 2,
  borderColor: Colors.teal,
  onTap: () => Navigator.push(context, ...),
)

// Custom error widget (overrides initials)
GlideCircle(
  imageUrl: url,
  radius: 36,
  name: 'Sam Lee',
  errorWidget: const Icon(Icons.person, size: 40),
)
```

---

### Standalone widgets

```dart
// InitialsAvatar — use anywhere without an image URL
InitialsAvatar(
  name: 'John Doe',        // → "JD"
  size: 64,
  backgroundColor: Colors.blueGrey,
  textColor: Colors.white,
)

// Single-letter name → "J"
InitialsAvatar(name: 'Jane', size: 48)

// ShimmerPlaceholder — use as a skeleton loader anywhere
ShimmerPlaceholder(
  width: 300,
  height: 180,
  baseColor: const Color(0xFFE0E0E0),
  highlightColor: const Color(0xFFF5F5F5),
)
```

---

## API Reference

### `GlideImage`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `imageUrl` *(required)* | `String` | — | Network URL, `assets/` path, SVG path, `file://` URI, or absolute file path |
| `width` | `double?` | `null` | Widget width |
| `height` | `double?` | `null` | Widget height |
| `fit` | `BoxFit` | `cover` | How the image fills its box |
| `borderRadius` | `BorderRadius?` | `null` | Rounded corners — applied to all source types |
| `color` | `Color?` | `null` | Tint colour; applied inside the clip via `ColorFiltered` |
| `colorBlendMode` | `BlendMode` | `srcIn` | Blend mode used with `color` |
| `onTap` | `VoidCallback?` | `null` | Tap callback |
| `placeholder` | `Widget?` | shimmer | Shown while a network image loads |
| `errorWidget` | `Widget?` | broken-image icon | Shown when loading fails or URL is empty |
| `shimmerBaseColor` | `Color` | `#E0E0E0` | Shimmer base colour |
| `shimmerHighlightColor` | `Color` | `#F5F5F5` | Shimmer highlight colour |
| `httpHeaders` | `Map<String,String>?` | `null` | Extra HTTP headers (network only) |
| `maxCacheWidth` | `int?` | `null` | Max memory-cache pixel width (network only) |
| `maxCacheHeight` | `int?` | `null` | Max memory-cache pixel height (network only) |

### `GlideBanner`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `imageUrl` *(required)* | `String` | — | Image source (same rules as `GlideImage`) |
| `aspectRatio` | `double` | `16/9` | Width ÷ height ratio |
| `overlayGradient` | `Gradient?` | `null` | Gradient painted over the image |
| `overlayColor` | `Color?` | `null` | Solid colour overlay (alternative to gradient) |
| `caption` | `String?` | `null` | Text shown at the bottom of the banner |
| `captionStyle` | `TextStyle?` | white bold w/ shadow | Text style for caption |
| `captionPadding` | `EdgeInsets` | `all(12)` | Padding around caption |
| `borderRadius` | `BorderRadius?` | `null` | Rounded corners |
| `onTap` | `VoidCallback?` | `null` | Tap callback |
| `placeholder` | `Widget?` | shimmer | Custom loading widget |
| `errorWidget` | `Widget?` | broken-image icon | Custom error widget |
| `shimmerBaseColor` | `Color` | `#E0E0E0` | Shimmer base colour |
| `shimmerHighlightColor` | `Color` | `#F5F5F5` | Shimmer highlight colour |

### `GlideGrid`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `imageUrls` *(required)* | `List<String>` | — | List of image sources |
| `crossAxisCount` | `int` | `3` | Number of columns |
| `spacing` | `double` | `2` | Gap between cells (horizontal & vertical) |
| `childAspectRatio` | `double` | `1` | Cell width ÷ height ratio |
| `borderRadius` | `BorderRadius?` | `null` | Rounded corners per cell |
| `fit` | `BoxFit` | `cover` | Image fit per cell |
| `onTap` | `void Function(int)?` | `null` | Tap callback — receives cell index |
| `placeholder` | `Widget?` | shimmer | Custom loading widget per cell |
| `errorWidget` | `Widget?` | broken-image icon | Custom error widget per cell |
| `shimmerBaseColor` | `Color` | `#E0E0E0` | Shimmer base colour |
| `shimmerHighlightColor` | `Color` | `#F5F5F5` | Shimmer highlight colour |

### `GlideCircle`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `imageUrl` *(required)* | `String` | — | Image source |
| `radius` *(required)* | `double` | — | Circle radius; diameter = `radius × 2` |
| `name` | `String` | `''` | Full name — up to 2 initials extracted automatically |
| `borderWidth` | `double` | `0` | Border stroke width |
| `borderColor` | `Color` | transparent | Border colour |
| `initialsBackgroundColor` | `Color` | `#D9D9D9` | Background colour behind initials |
| `initialsTextColor` | `Color` | `#555555` | Initials text colour |
| `onTap` | `VoidCallback?` | `null` | Tap callback |
| `errorWidget` | `Widget?` | initials | Overrides initials on load error |
| `httpHeaders` | `Map<String,String>?` | `null` | Extra HTTP headers (network only) |
| `shimmerBaseColor` | `Color` | `#E0E0E0` | Shimmer base colour |
| `shimmerHighlightColor` | `Color` | `#F5F5F5` | Shimmer highlight colour |

### `InitialsAvatar`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` *(required)* | `String` | — | Name to extract initials from |
| `size` *(required)* | `double` | — | Width and height of the box |
| `backgroundColor` | `Color` | `#D9D9D9` | Background fill colour |
| `textColor` | `Color` | `#555555` | Initials text colour |
| `fontSize` | `double?` | `size × 0.38` | Override font size |

### `ShimmerPlaceholder`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `width` | `double?` | `null` | Width of the placeholder |
| `height` | `double?` | `null` | Height of the placeholder |
| `baseColor` | `Color` | `#E0E0E0` | Shimmer base colour |
| `highlightColor` | `Color` | `#F5F5F5` | Shimmer sweep colour |

---

## Source resolution

`resolveImageSource(url)` is the shared resolver used by all widgets. Resolution order:

| Priority | Condition | Resolved as |
|---|---|---|
| 1 | Blank / whitespace-only | `unknown` → fallback widget |
| 2 | Starts with `http://` or `https://` | `network` → `CachedNetworkImage` |
| 3 | Starts with `assets/` or `asset/`, ends with `.svg` | `assetSvg` → `SvgPicture.asset` |
| 4 | Starts with `assets/` or `asset/` | `asset` → `Image.asset` |
| 5 | Starts with `file://` or is an absolute/relative path | `file` → `Image.file` |

`file://` URIs are automatically converted to a file path via `Uri.parse().toFilePath()` before
being passed to `Image.file`.

---

## Dependencies

| Package | Version | Purpose |
|---|---|---|
| `cached_network_image` | `^3.3.1` | Network image caching |
| `flutter_svg` | `^2.0.10` | SVG rendering |
| `shimmer` | `^3.0.0` | Shimmer loading animation |

---

## License

MIT