Skip to main content

​
Examples

​
Properties

​
Required

​
List<NeoPickedFile>
required
The files to show. You own this list. Pass the list from onChanged back here.
​
ValueChanged<List<NeoPickedFile>>
required
Called with the next list when a file is added or removed. A cancelled picker does not call this. A batch where every file is rejected does not call this.

​
Content

​
String?
Text shown above the drop zone.
​
String?
Helper text shown under the drop zone. Hidden while an error is showing.
​
String?
Error text shown under the drop zone. A non-empty value replaces the picker’s own error.
​
String?
Text in the drop zone. The default is “Select or drop files”. With allowMultiple: false, the default is “Select or drop a file”.
​
List<String>?
Extensions to accept, with or without a leading dot. Comparison ignores case. null, an empty list, or a list of blank values accepts any file. A file with no extension is rejected when a list is set. The system picker and drops both use this list.
​
String? Function(NeoFilePickerError)?
Maps a NeoFilePickerError to the message under the drop zone. Return a string to replace the default for that error. Return null, or omit this, to show NeoFilePickerError.defaultMessage.

​
Layout

​
int
default:"104857600 (100MB)"
Maximum file size in bytes. A larger file is rejected with fileTooLarge. The check uses the file’s byte length.
​
int?
Maximum number of files in files. A file past this limit is rejected with tooManyFiles. Files from the same batch that still fit are kept. null means no limit.
​
bool
default:"true"
Shows a remove button on each file. The button is hidden while the picker is disabled, reading a file, or a drag is over the zone. Removing a file clears the picker’s own error and calls onChanged.

​
State

​
bool
default:"true"
When true, new files are appended to files. When false, the next accepted file replaces files. Dropping more than one file while this is false reports tooManyFiles and leaves files unchanged.
​
bool
default:"true"
When false, the drop zone dims, ignores taps and drops, and shows a forbidden cursor. Remove buttons stay hidden.

​
File

NeoPickedFile is one file in files and in the list passed to onChanged.

​
Required

​
String
required
The file name, without a directory. An empty name becomes File.
​
int
required
Length of bytes.
​
Uint8List
required
The full file contents. The picker reads the file into memory before it calls onChanged.

​
Content

​
String?
The extension without a leading dot, in lowercase. null when the name has none.
​
String?
The path from the system file picker, when the platform provides one. A dropped file does not set this.

​
Enums

​
NeoFilePickerError

Errors from a pick or a drop. defaultMessage is the text used when you omit onError or return null.
  • fileTooLarge: The file is larger than maxFileSize. Default message: “File size exceeds limit”.
  • unsupportedFormat: The extension is not in allowedExtensions. Default message: “Unsupported file type”.
  • tooManyFiles: The list would pass maxCount, or more than one file was dropped while allowMultiple is false. Default message: “Too many files”.
  • pickFailed: The system picker failed to open or return a result. Default message: “Failed to pick file”.
  • readFailed: The file could not be read. A drop that takes longer than 30 seconds uses this error. Default message: “Failed to read file”.
  • dropFailed: The drop could not be processed, or none of the dropped items could be read as a file. Default message: “Failed to process dropped file”.

​
Best Practices

  • Keep files in your own state, and set that state from onChanged.
  • Set allowedExtensions and a lower maxFileSize when the upload only accepts certain files.

​
Behavior

  • The drop zone is 160 tall and fills the available width. The border is dotted.
  • A drag over the zone paints the border with theme.colors.success. An error paints it with theme.colors.danger.
  • Cancelling the system picker clears the picker’s own error and leaves files unchanged.
  • Files in one batch that pass are still added when another file in that batch is rejected. The first rejection is the error you see.
  • Each row shows an icon for the extension, the file name, and the size in B, KB, or MB.
  • While a file is being read, the zone ignores further taps and drops.
Last modified on October 5, 2026