unified_file_picker #

Cross-platform file and folder picker for Flutter with a unified, fully customizable explorer-style UI.
Published by quds.cc

Instead of relying on each platform's native dialog, unified_file_picker renders one consistent Flutter interface on Android, iOS, Windows, Linux, and macOS — with list/details/tiles/icons views, recursive search, keyboard shortcuts, thumbnails, and RTL support.

Table of contents #

• Features
• Platform support
• Installation
• Setup
• Quick start
• API overview
• Picker modes
• File type filters
• View modes
• Explorer UI
• Keyboard shortcuts
• Theming
• Localization
• Embedding the picker
• Saving files
• Return values
• Example app
• License

Features #

Core capabilities #

• Open files - single or multiple selection with preset or custom type filters
• Pick folders - navigate into subfolders on desktop; confirm current folder or selected folders
• Save files - choose destination folder, edit file name, optional overwrite confirmation
• Write bytes - persist data to a path returned by the save dialog

Explorer UI #

• Breadcrumb path bar - click segments to navigate; click the current segment or background to type/paste a full path (Enter navigates, Escape cancels)
• Navigation history - back, forward, and go-up controls
• Quick-access sidebar - Home, Desktop, Documents, Downloads, Pictures, Videos, Music, and drives/volumes (layout adapts to available width)
• Four view modes -list, details (sortable table), tiles, and icons with zoom controls
• Recursive search - search within the current folder tree with progress and cancel (desktop)
• Thumbnails - image and video previews where supported
• Context menu - sort by name/modified/type/size; switch view mode (desktop right-click)
• Marquee selection - drag to select multiple items (desktop, multi-select modes)
• Animated folder transitions - smooth content changes when navigating

Customization #

• Full theming - colors, typography, modal dimensions, sidebar width, per-kind icon overrides
• Presentation - modal dialog or fullscreen route with configurable enter/exit animations
• Localization - English and Arabic built-in; override any string per session
• RTL - layout direction support via textDirection or app locale
• Adaptive chrome - Material on most platforms; Cupertino navigation on iOS/macOS

Platform support #

Desktop platforms use a pure Dart dart:io backend and do not require native filesystem code. Mobile platforms use a platform channel (unified_file_picker) for gallery access and permissions.

Installation #

Add to your pubspec.yaml:

dependencies:
  unified_file_picker: ^0.1.3

Then run:

flutter pub get

Requirements: Dart SDK ^3.12.2, Flutter >=3.3.0.

Setup #

Register the localization delegate in your app (required for built-in UI strings):

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:unified_file_picker/unified_file_picker.dart';

MaterialApp(
  localizationsDelegates: const [
    UnifiedFilePickerLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'),
    Locale('ar'),
  ],
  // ...
);

Quick start #

Pick files #

final files = await UnifiedFilePicker.pickFiles(
  context,
  type: FilePickerType.images,
  selection: SelectionMode.multiple,
);

if (files != null) {
  for (final file in files) {
    print('${file.name} → ${file.path}');
  }
}

Pick a folder #

final folders = await UnifiedFilePicker.pickFolder(context);

if (folders != null && folders.isNotEmpty) {
  print('Selected: ${folders.first.path}');
}

Save a file #

final location = await UnifiedFilePicker.saveFile(
  context,
  suggestedFileName: 'report.pdf',
  type: FilePickerType.documents,
);

if (location != null) {
  final success = await UnifiedFilePicker.writeBytes(location, pdfBytes);
}

Full control with options #

final result = await UnifiedFilePicker.pick(
  context,
  options: FilePickerOptions(
    mode: FilePickerMode.open,
    type: FilePickerType.images,
    selection: SelectionMode.multiple,
    initialViewMode: FilePickerViewMode.tiles,
    showThumbnails: true,
    presentation: FilePickerPresentation.modal,
    theme: const FilePickerTheme(
      title: 'Choose photos',
      primaryColor: Color(0xFF5B4FCF),
      borderRadius: 16,
    ),
  ),
);

API overview #

UnifiedFilePicker #

Presentation helpers #

Options factory #

Use FilePickerOptionsFactory for opinionated defaults, then copyWith for overrides:

final options = FilePickerOptionsFactory.openFiles(
  type: FilePickerType.documents,
  selection: SelectionMode.single,
).copyWith(
  initialDirectory: '/home/user/Documents',
  barrierDismissible: false,
);

Picker modes #

FilePickerMode.open #

Pick one or more files from the filesystem or mobile gallery.

• Filter by FilePickerType preset or custom FileTypeFilter list
• Optional thumbnails for images and videos
• Single-click to select, double-click to open on desktop

FilePickerMode.folder #

Pick one or more folders.

• On desktop: single-click selects, double-click enters a folder
• Use this folder action confirms the current directory without selecting a child
• Folder filter dropdown is hidden

FilePickerMode.save #

Choose a destination folder and file name.

• Pre-fills suggestedFileName
• File-type filter can append the correct extension
• Optional overwrite confirmation when confirmExistingFile is true (default)

Selection #

enum SelectionMode {
  single,   // one item at confirm
  multiple, // Ctrl/Cmd+click, Shift+range, marquee, Select All
}

File type filters #

Preset types (FilePickerType) #

Custom filters #

await UnifiedFilePicker.pickFiles(
  context,
  customFilters: const [
    FileTypeFilter(
      label: 'Markdown',
      extensions: ['.md', '.markdown'],
      mimeTypes: ['text/markdown'],
    ),
    FileTypeFilter(
      label: 'Archives',
      extensions: ['.zip', '.tar', '.gz'],
    ),
  ],
  initialFilter: /* optional FileTypeFilter */,
);

When customFilters is non-empty, it replaces the default filter derived from FilePickerType.

View modes #

Configure via initialViewMode and allowedViewModes:

Tiles and icons modes include a zoom slider (0.7×–1.8×). Restrict available modes:

allowedViewModes: [
  FilePickerViewMode.list,
  FilePickerViewMode.details,
],

Explorer UI #

Breadcrumb path bar #

• Shows the current path as clickable segments
• Click any segment to jump to that folder
• Click the last segment or empty area to enter edit mode — type or paste a full path
• Enter navigates immediately; Escape cancels
• On Windows, paths display with backslashes (e.g. C:\Users\…)

Quick-access sidebar #

When showShortcutsSidebar is true (default):

• Quick access — OS-specific shortcuts (Home, Desktop, Documents, Downloads, Pictures, Videos, Music)
• This PC — drives and mounted volumes
• Wide layouts show a vertical sidebar; compact layouts use a horizontal chip bar

On Windows, the empty path shows This PC with drive tiles including volume label, capacity bar, and free/total space.

Search #

Recursive folder search is available on desktop when browsing a real directory (not at the This PC root):

• Type in the search bar to scan subfolders
• Progress indicator and stop button during search
• Skips hidden and build directories (.git, node_modules, build, …)

Sorting #

Sort folder contents by name, modified, type, or size (ascending/descending):

• Click column headers in details view
• Use the right-click context menu on desktop

Directories always sort before files.

Selection behavior #

The confirm button shows the selection count in multi-select mode.

Keyboard shortcuts #

Theming #

Pass a FilePickerTheme to any pick method or embed it in FilePickerOptions:

const theme = FilePickerTheme(
  primaryColor: Color(0xFF5B4FCF),
  backgroundColor: Color(0xFF1E1E2E),
  textColor: Colors.white,
  borderRadius: 16,
  modalMaxWidth: 1024,
  modalMaxHeight: 720,
  sidebarWidth: 240,
  title: 'Choose files',
  confirmLabel: 'Open',
  cancelLabel: 'Cancel',
  iconOverrides: {
    FileEntryKind.folder: Icons.folder_special_rounded,
    FileEntryKind.drive: Icons.storage_rounded,
  },
);

Customizable properties #

Unset values inherit from the host app's ThemeData via mergeWithTheme. The picker also builds a harmonized ThemeData for internal Material widgets.

Presentation and transitions #

FilePickerOptions(
  presentation: FilePickerPresentation.modal, // or .fullscreen
  transition: FilePickerTransition(
    kind: FilePickerTransitionKind.slideUp, // fade, slideFromStart, scale
    duration: Duration(milliseconds: 280),
    curve: Curves.easeOutCubic,
  ),
  barrierDismissible: true,
)

Localization #

Built-in locales:

Override strings per session #

Extend UnifiedFilePickerStrings (or EnglishFilePickerStrings) and pass via FilePickerOptions.strings:

class BrandStrings extends EnglishFilePickerStrings {
  const BrandStrings();

  @override
  String get selectFiles => 'Choose attachments';

  @override
  String get thisPc => 'My Computer';
}

await UnifiedFilePicker.pick(
  context,
  options: FilePickerOptions(
    strings: const BrandStrings(),
    textDirection: TextDirection.rtl, // optional explicit direction
  ),
);

The strings interface covers titles, action buttons, sidebar sections, sorting/view labels, search messages, path bar hints, save/overwrite dialogs, empty states, and permission prompts.

Embedding the picker #

Use FilePickerScreen to embed the explorer inside your own navigation instead of a modal:

FilePickerScreen(
  options: myOptions,
  // Optional: inject a custom FileSystemService for testing
)

Or call the lower-level helpers directly:

await showUnifiedFilePickerModal(context, options: myOptions);
await showUnifiedFilePickerRoute(context, options: myOptions);

Saving files #

Typical workflow #

// 1. Show save dialog
final location = await UnifiedFilePicker.saveFile(
  context,
  suggestedFileName: 'export.csv',
  type: FilePickerType.documents,
  confirmExistingFile: true,
);

if (location == null) return; // user cancelled

// 2. Write data
final ok = await UnifiedFilePicker.writeBytes(location, csvBytes);

Additional helpers #

// Copy an existing file to the save location
await SaveFileHelper.copyFrom(location, '/path/to/source.pdf');

// Check whether the target already exists
final exists = await SaveFileHelper.exists(location);

On save, the file-type filter can automatically append the correct extension via ensureExtension.

Return values #

PickedFile fields #

Example app #

The example/ app is a live customization demo. Run it from the plugin root:

cd example
flutter pub get
flutter run

Or use the example launch config in .vscode/launch.json.

The demo includes:

• Live embedded preview of FilePickerScreen
• Theme controls — accent color, dark mode, corner radius, modal size, sidebar width
• Presentation and transition pickers
• View mode and thumbnail toggles
• Custom strings and icon overrides
• English ↔ Arabic locale toggle with RTL
• Pick files, pick folder, and save file actions with result display

See example/README.md for additional run options and troubleshooting.

License #

MIT — see LICENSE.

Links #

• Repository: github.com/MohammedAsaadAsaad/unified_file_picker
• Issues: github.com/MohammedAsaadAsaad/unified_file_picker/issues