File Picker

A customizable file picker component with validation, preview, and multiple file support.

Installation


pnpm dlx bna-ui add file-picker

Usage

import { FilePicker } from '@/components/ui/file-picker';

<FilePicker
  onFilesSelected={(files) => console.log('Selected files:', files)}
  onError={(error) => console.error('Error:', error)}
  fileType='all'
  multiple={true}
  maxFiles={5}
  placeholder='Select your files'
/>

Examples

Default

Image Only

Single File

With Validation

Custom Styling

Controlled

With File Info

API Reference

FilePicker

The main file picker component.

Prop	Type	Default	Description
`onFilesSelected`	`(files: SelectedFile[]) => void`	-	Callback when files are selected.
`onError?`	`(error: string) => void`	-	Callback when an error occurs.
`fileType?`	`'image' \| 'document' \| 'all'`	`'all'`	Type of files to allow.
`multiple?`	`boolean`	`false`	Whether to allow multiple file selection.
`maxFiles?`	`number`	`10`	Maximum number of files to select.
`maxSizeBytes?`	`number`	`10MB`	Maximum file size in bytes.
`allowedExtensions?`	`string[]`	-	Array of allowed file extensions.
`placeholder?`	`string`	`'Select files'`	Placeholder text for the picker button.
`disabled?`	`boolean`	`false`	Whether the picker is disabled.
`style?`	`ViewStyle`	-	Additional styles for the container.
`showFileInfo?`	`boolean`	`true`	Whether to show file size information.
`accessibilityLabel?`	`string`	-	Accessibility label for the picker button.
`accessibilityHint?`	`string`	-	Accessibility hint for the picker button.

SelectedFile

The file object structure returned by the component.

Property	Type	Description
`uri`	`string`	The file URI.
`name`	`string`	The file name.
`type?`	`string`	The file MIME type.
`size?`	`number`	The file size in bytes.
`mimeType?`	`string`	The file MIME type.

useFilePicker Hook

A hook for managing file picker state programmatically.

const { files, addFiles, removeFile, clearFiles, totalSize, isValid, errors } =
  useFilePicker({
    maxFiles: 5,
    maxSizeBytes: 5 * 1024 * 1024, // 5MB
    allowedExtensions: ['pdf', 'doc', 'docx'],
    onError: (error) => console.error(error),
  });

Options

Property	Type	Default	Description
`maxFiles?`	`number`	`10`	Maximum number of files.
`maxSizeBytes?`	`number`	`10MB`	Maximum file size in bytes.
`allowedExtensions?`	`string[]`	-	Array of allowed file extensions.
`onError?`	`(error: string) => void`	-	Callback when an error occurs.

Return Value

Property	Type	Description
`files`	`SelectedFile[]`	Array of selected files.
`addFiles`	`(files: SelectedFile[]) => void`	Function to add files.
`removeFile`	`(index: number) => void`	Function to remove a file by index.
`clearFiles`	`() => void`	Function to clear all files.
`totalSize`	`number`	Total size of all files in bytes.
`isValid`	`boolean`	Whether the current state is valid.
`errors`	`string[]`	Array of validation errors.

Utility Functions

createFileFromUri

const file = await createFileFromUri(uri, 'custom-name.pdf');

validateFiles

const { valid, errors } = validateFiles(files, {
  maxSize: 5 * 1024 * 1024,
  allowedExtensions: ['pdf', 'doc'],
  maxFiles: 3,
});

File Types

The component supports three file type modes:

'all' - All file types (default)
'image' - Images only (jpg, jpeg, png, gif, webp, etc.)
'document' - All file types with document picker

Validation

The FilePicker includes built-in validation for:

File size - Configurable maximum size per file
File extensions - Whitelist of allowed extensions
File count - Maximum number of files
MIME types - Automatic validation based on file type

Accessibility

The FilePicker component is built with accessibility in mind:

Proper accessibility labels and hints
Screen reader support for file information
Keyboard navigation support
Clear error messaging
Semantic button structure

Best Practices

Set appropriate file size limits to prevent memory issues
Use specific file type restrictions when possible
Provide clear error messages to guide users
Show file previews when relevant
Handle loading states for better UX
Validate files on both client and server side

Date Picker Gallery