Image Picker

​

Examples

• Basic
• With Label & Description
• Custom Error Handling

Basic Usage

NeoImagePicker(
  currentImage: imageBytes,
  onChanged: (bytes) {
    imageBytes = bytes;
  },
),

With Label

NeoImagePicker(
  currentImage: imageBytes,
  onChanged: (bytes) {
    imageBytes = bytes;
  },
  label: "Profile Picture",
  description: "Max 5MB.",
  maxFileSize: 5 * 1024 * 1024,
),

Custom Errors

NeoImagePicker(
  currentImage: imageBytes,
  onChanged: (bytes) {
    imageBytes = bytes;
  },
  onError: (error) => switch (error) {
    .fileTooLarge => "Image must be under 10MB",
    _ => null, // Falls back to default message
  },
),

​

Properties

​

Required

​

Content

​

Layout

​

State

​

Enums

​

NeoImagePickerError

• fileTooLarge: The selected file exceeds maxFileSize.
• unsupportedFormat: The dropped file is not a supported image format.
• pickFailed: The file picker failed to open or return a result.
• readFailed: The file could not be read from disk.
• dropFailed: The drag-and-drop operation failed.
• renderFailed: The image bytes could not be rendered (invalid format).
• unknown: An unexpected error occurred.

​

Best Practices

• Set a reasonable maxFileSize: The default 100MB limit is generous. For profile pictures or thumbnails, set a lower limit (e.g., 5 * 1024 * 1024 for 5MB) or compress on the server side.
• Provide custom error messages with onError: Tailor error messages to your use case or language for a better user experience.
• Size the drop zone: Prefer dropZoneWidth / dropZoneHeight over wrapping in SizedBox when you need a fixed picker size. Unconstrained height defaults to 240.

​

Integration Notes

• Supported formats: PNG, JPEG, GIF, WebP, HEIC, HEIF, BMP, and TIFF.
• Loading state: The picker automatically shows a loading overlay while processing files or drag-and-drop operations.
• Image display: Selected images are displayed with BoxFit.contain. On hover, a swap icon overlay appears to indicate the image can be replaced.
• Drag-over highlight: While dragging a supported image over the drop zone, the border uses the theme success color.