> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# File Picker

> A drop zone for picking or dropping files, with extension, size, and count limits.

## Examples

<Tabs>
  <Tab title="Basic">
    <CodeGroup>
      ```dart Basic Usage lines theme={null}
      NeoFilePicker(
        files: files,
        onChanged: (next) {
          files = next;
        },
        label: "Receipts",
        description: "PDF, spreadsheet, or photo.",
      ),
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Single File">
    <CodeGroup>
      ```dart Single File lines theme={null}
      NeoFilePicker(
        files: files,
        onChanged: (next) {
          files = next;
        },
        allowMultiple: false,
        label: "Signed contract",
      ),
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Limits">
    <CodeGroup>
      ```dart Limits lines theme={null}
      NeoFilePicker(
        files: files,
        onChanged: (next) {
          files = next;
        },
        label: "Contract",
        description: "PDF files only.",
        allowedExtensions: ["pdf"],
        maxFileSize: 1024 * 1024,
        maxCount: 3,
        onError: (error) => switch (error) {
          .fileTooLarge => "Choose a file under 1 MB",
          _ => null,
        },
      ),
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Properties

### Required

<ParamField path="files" type="List<NeoPickedFile>" required>
  The files to show. You own this list. Pass the list from `onChanged` back here.
</ParamField>

<ParamField path="onChanged" type="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.
</ParamField>

### Content

<ParamField path="label" type="String?">
  Text shown above the drop zone.
</ParamField>

<ParamField path="description" type="String?">
  Helper text shown under the drop zone. Hidden while an error is showing.
</ParamField>

<ParamField path="errorText" type="String?">
  Error text shown under the drop zone. A non-empty value replaces the picker's own error.
</ParamField>

<ParamField path="placeholder" type="String?">
  Text in the drop zone. The default is "Select or drop files". With `allowMultiple: false`, the default is "Select or drop a file".
</ParamField>

<ParamField path="allowedExtensions" type="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.
</ParamField>

<ParamField path="onError" type="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`.
</ParamField>

### Layout

<ParamField path="maxFileSize" type="int" default="104857600 (100MB)">
  Maximum file size in bytes. A larger file is rejected with `fileTooLarge`. The check uses the file's byte length.
</ParamField>

<ParamField path="maxCount" type="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.
</ParamField>

<ParamField path="showRemoveButton" type="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`.
</ParamField>

### State

<ParamField path="allowMultiple" type="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.
</ParamField>

<ParamField path="isEnabled" type="bool" default="true">
  When false, the drop zone dims, ignores taps and drops, and shows a forbidden cursor. Remove buttons stay hidden.
</ParamField>

## File

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

### Required

<ParamField path="name" type="String" required>
  The file name, without a directory. An empty name becomes `File`.
</ParamField>

<ParamField path="size" type="int" required>
  Length of `bytes`.
</ParamField>

<ParamField path="bytes" type="Uint8List" required>
  The full file contents. The picker reads the file into memory before it calls `onChanged`.
</ParamField>

### Content

<ParamField path="extension" type="String?">
  The extension without a leading dot, in lowercase. `null` when the name has none.
</ParamField>

<ParamField path="path" type="String?">
  The path from the system file picker, when the platform provides one. A dropped file does not set this.
</ParamField>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.