README

A beautiful and customizable image picker component for Laravel applications with drag-and-drop support, multiple preview types, and file validation.

Features

• 🖼️ Drag & Drop Support - Intuitive file upload interface
• 📱 Responsive Design - Works on all device sizes
• 🎨 Multiple Preview Types - Grid, list, thumbnail, dropdown, and file views
• ✅ File Validation - Built-in size and type validation
• 🔄 Multiple Files - Support for single or multiple file uploads
• 🎯 Easy Integration - Simple Blade component usage
• 📦 Zero Dependencies - Pure JavaScript, no external libraries required

Installation

1. Install the package

composer require mhshagor/file-picker

If you are not using Laravel, you do not need Composer. Use the standalone instructions below.

2. Publish Assets

Publish the CSS and JS files to your resources folder:

php artisan vendor:publish --tag=file-picker

This will copy files to:

• resources/js/vendor/file-picker/file-picker.js
• resources/css/vendor/file-picker/file-picker.css

3. Add to your app.js

Add this line to your resources/js/app.js:

import "./vendor/file-picker/file-picker.js";

4. Add to your app.css

Add this line to your resources/css/app.css:

@import "./vendor/file-picker/file-picker.css";

5. Compile your assets

npm run dev
# or
npm run build

Usage

Basic Usage

<x-file-picker
    name="profile_image"
    label="Profile Image"
    preview-type="profile"
/>

Advanced Usage

<x-file-picker
    name="gallery_images"
    label="Gallery Images"
    :multiple="true"
    max="10"
    type="image"
    preview-type="grid"
    :required="true"
    class="custom-class"
/>

Standalone HTML/JS Usage (No Laravel)

Copy these files from the package into your project and include them in your HTML:

• CSS: /vendor/mhshagor/file-picker/assets/css/file-picker.css -> public/css/file-picker.css
• JS: /vendor/mhshagor/file-picker/assets/js/file-picker.js -> public/js/file-picker.js
• Demo HTML: /vendor/mhshagor/file-picker/assets/demo/file-picker.html -> ./file-picker.html

Then use:

• CSS: public/css/file-picker.css
• JS: public/js/file-picker.js

Example:

<link rel="stylesheet" href="public/css/file-picker.css" />

<input
  class="file-picker"
  name="files"
  id="files"
  max="5"
  multiple="true"
  type="image"
  accept="image/*"
  preview="true"
  preview-type="grid"
/>

<script src="public/js/file-picker.js"></script>

Parameters

Preview Types

Profile Preview

preview-type="profile"

Shows a circular profile picture preview.

Grid Preview

preview-type="grid"

Shows files in a responsive grid layout with thumbnails.

List Preview

preview-type="list"

Displays files in a vertical list with thumbnails and filenames.

Thumbnail Preview

preview-type="thumbnail"

Shows small thumbnails in a compact horizontal layout.

File Preview

preview-type="file"

Displays files as downloadable links.

Dropdown Preview

preview-type="dropdown"

Shows a dropdown with file count and list when clicked.

File Validation

The component includes built-in validation:

• File Type Validation: Automatically validates file types based on the type parameter
• Size Validation: Validates file size against the max parameter
• Error Messages: User-friendly error messages with auto-dismiss

Styling

The component uses Tailwind CSS classes and includes:

• base-input - Base input styling
• base-label - Base label styling
• Responsive design classes
• Hover and focus states
• Error state styling

You can customize the appearance by:

1. Overriding the CSS classes
2. Adding custom classes via the class parameter
3. Modifying the published Blade component

Form Integration

The component integrates seamlessly with Laravel forms:

<form method="POST" enctype="multipart/form-data">
    @csrf

    <x-file-picker
        name="avatar"
        label="Upload Avatar"
        preview-type="profile"
        :required="true"
    />

    <button type="submit">Submit</button>
</form>

Error Handling

The component automatically displays Laravel validation errors:

@error('avatar')
    <p class="text-red-500 text-xs mt-1">{{ $message }}</p>
@enderror

File Processing

In your controller, handle the uploaded files:

public function store(Request $request)
{
    $request->validate([
        'avatar' => 'required|image|mimes:jpeg,png,jpg,gif|max:2048',
        'gallery_images.*' => 'image|mimes:jpeg,png,jpg,gif|max:2048'
    ]);

    if ($request->hasFile('avatar')) {
        $file = $request->file('avatar');
        $path = $file->store('avatars', 'public');
        // Save path to database
    }

    if ($request->hasFile('gallery_images')) {
        foreach ($request->file('gallery_images') as $file) {
            $path = $file->store('gallery', 'public');
            // Save path to database
        }
    }
}

Customization

Custom Component Location

If you want to customize the component, you can modify the published files:

• Views: resources/views/components/file-picker.blade.php
• JavaScript: resources/js/vendor/file-picker/file-picker.js

Custom Styling

Add custom CSS to override default styles:

.file-picker .base-input {
  /* Custom input styling */
}

.file-picker .base-label {
  /* Custom label styling */
}

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This package is open-sourced software licensed under the MIT license.

Support

For support, please contact mhshagor.

Made with ❤️ for the Laravel community