# Magic Picker

**Pick a file, get a MagicFile back.**

A `Pick` facade for apps on the Magic framework: open the gallery, the camera, the file dialog and the save dialog, and get a `MagicFile` from the pickers.

## Pick, save and share files.

The `Pick` facade opens the gallery, the camera, the file dialog and the save dialog. It covers Android, iOS, web, macOS, Windows and Linux, with two exceptions listed below.

### Gallery picks

`Pick.image`, `Pick.images`, `Pick.media` and `Pick.video` open the gallery and return a `MagicFile`; `Pick.images` returns an empty list on cancel.

[Learn more about Gallery picks](https://anilcancakir.com/magic/docs/picker/basics/pick.md)

### Camera capture

`Pick.camera` and `Pick.recordVideo` take a `fallbackToGallery` option and an `onError` callback. On desktop the camera needs a custom `image_picker` delegate.

[Learn more about Camera capture](https://anilcancakir.com/magic/docs/picker/basics/pick.md)

### System file dialog

`Pick.file`, `Pick.files` and `Pick.directory` open the system file dialog, with an optional `extensions` filter. `Pick.directory` returns a path and is not on the web.

[Learn more about System file dialog](https://anilcancakir.com/magic/docs/picker/basics/pick.md)

### Save dialog

`Pick.saveFile` opens the save dialog and returns a `Uri?`: scheme `file` on desktop and iOS, `content` on Android, `blob` on the web.

[Learn more about Save dialog](https://anilcancakir.com/magic/docs/picker/basics/pick.md)

### Convert both ways

`XFile.toMagicFile()` and `MagicFile.toXFile()` convert both ways. Bytes are read lazily through `bytesReader`; on the web `toXFile` is asynchronous.

[Learn more about Convert both ways](https://anilcancakir.com/magic/docs/picker/basics/xfile.md)

### Share sheet downloads

`PickerServiceProvider` sets the download handler, so `Storage.download` opens the share sheet on mobile and desktop. On the web a download starts in the browser.

[Learn more about Share sheet downloads](https://anilcancakir.com/magic/docs/picker/basics/download.md)

## Add it in seconds

```bash
flutter pub add magic_picker
```

Or add to `pubspec.yaml`:

```yaml
dependencies:
  magic_picker: ^1.0.1
```

Or give your AI agent this prompt:

```text
Read https://anilcancakir.com/magic/docs/picker/llms.txt and install the Magic Picker package in this project.
```

## Docs

### Getting Started

- [Installation](https://anilcancakir.com/magic/docs/picker/getting-started/installation.md)

### The Basics

- [Pick](https://anilcancakir.com/magic/docs/picker/basics/pick.md)
- [Download](https://anilcancakir.com/magic/docs/picker/basics/download.md)
- [XFile Conversion](https://anilcancakir.com/magic/docs/picker/basics/xfile.md)

### Guides

- [Testing](https://anilcancakir.com/magic/docs/picker/guides/testing.md)