hinted_image_picker

A Flutter widget that wraps image_picker to show a customizable hint image before selection and a thumbnail after — with InkWell ripple, hover elevation, and a lightened hint overlay with a pickable icon. Includes a multi-image variant with a +N count badge.

	Single	Multi
Hint state	✅	✅
Thumbnail	✅	✅ (first image)
`+N` badge	—	✅
Ripple / hover / elevation	✅	✅

Features

Lightened hint image with a centered, customizable overlay icon
Thumbnail preview after picking (Image.memory, web-safe — no dart:io)
InkWell ripple + hover elevation on desktop/web pointer devices
Circle, rounded, or square shape
Source selector (camera/gallery) bottom sheet, or force a single source
Multi-image picker with a +N badge showing how many additional images were selected
Remove/clear button

Installation

dependencies:
  hinted_image_picker: ^0.1.0

flutter pub get

Platform setup

This package uses image_picker under the hood, which requires platform-specific permission declarations in the app that consumes this package — not in the package itself.

iOS

Add to ios/Runner/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access to let you pick an image.</string>
<key>NSCameraUsageDescription</key>
<string>This app needs camera access to let you take a photo.</string>

Android

image_picker handles runtime permissions automatically on modern Android. Confirm minSdkVersion is 21+ in android/app/build.gradle.

macOS

Add to both macos/Runner/DebugProfile.entitlements and Release.entitlements:

<key>com.apple.security.files.user-selected.read-only</key>
<true/>

Web

No extra setup — picking works via the browser's file input. Camera capture support depends on the browser.

Usage

Single image picker

import 'package:hinted_image_picker/hinted_image_picker.dart';

HintedImagePicker(
  hintAssetPath: 'assets/hint.png',
  size: 120,
  shape: PickerShape.circle,
  overlayIcon: Icons.camera_alt_outlined, // default: Icons.image_outlined
  overlayIconColor: Colors.blue,          // default: Theme primary color
  hintLightenAmount: 0.4,                 // 0.0–1.0
  onImagePicked: (file) => print(file.path),
  onImageRemoved: () => print('cleared'),
  onError: (e) => print('error: $e'),
)

Multi image picker

HintedMultiImagePicker(
  hintAssetPath: 'assets/hint.png',
  size: 120,
  shape: PickerShape.rounded,
  maxImages: 10,
  onImagesPicked: (files) => print('${files.length} images picked'),
  onImagesCleared: () => print('cleared'),
  onError: (e) => print('error: $e'),
)

The multi picker shows the first selected image as the thumbnail with a +N badge in the bottom-right corner, where N is the number of additional images (total minus one), not the raw total.

Tapping the widget again replaces the entire selection — it does not append to the existing one. This mirrors the underlying pickMultiImage platform behavior, which always returns a fresh full selection rather than an incremental one. If you need per-image review or removal, use onImagesPicked's List<XFile> to drive a separate full-screen gallery UI; this widget is a compact preview, not a selection manager.

HintedImagePicker(
  hintWidget: Icon(Icons.person, size: 48),
  // ...
)

Either hintAssetPath or hintWidget is required — an assertion fires at construction if neither is provided. The lighten overlay and overlay icon are applied on top of whichever hint you pass, including custom widgets.

API reference

Both widgets share the same visual/interaction configuration.

Property	Type	Default	Description
`hintWidget` / `hintAssetPath`	`Widget?` / `String?`	—	One is required. Shown before an image is picked.
`size`	`double`	`100`	Width/height of the picker (square bounding box).
`shape`	`PickerShape`	`circle`	`circle`, `rounded`, or `square`.
`borderRadius`	`BorderRadius?`	`12` (rounded only)	Only used when `shape` is `rounded`.
`border`	`BoxBorder?`	`null`	Optional border decoration.
`allowRemove`	`bool`	`true`	Shows an "×" button to clear the selection.
`enabled`	`bool`	`true`	Disables tap interaction when `false`.
`imageQuality`	`int?`	`85`	Passed through to `image_picker`.
`maxWidth` / `maxHeight`	`double?`	`null`	Passed through to `image_picker`.
`elevation` / `hoverElevation`	`double`	`1` / `4`	Shadow depth at rest / on hover (desktop, web).
`splashColor` / `hoverColor`	`Color?`	theme default / `black 4%`	`InkWell` interaction colors.
`overlayIcon`	`IconData`	`Icons.image_outlined`	Icon centered over the hint.
`overlayIconColor`	`Color?`	`Theme.of(context).colorScheme.primary`	Overlay icon color.
`overlayIconSize`	`double?`	`size / 3`	Overlay icon size.
`hintLightenAmount`	`double`	`0.4`	White overlay opacity on the hint, `0.0`–`1.0`.
`onError`	`ValueChanged<Object>?`	`null`	Called if `image_picker` throws.