DOCSEARCHbyAlgolia
Submit Docs

vuefinder

repository·master·Indexed 20 days ago

https://github.com/n1crack/vuefinder

A modern, customizable file manager component for Vue 3 (version 4.6.0) that provides a reactive, native-like file explorer interface. It is backend-agnostic and connects to storage via a Driver interface, with built-in support for ArrayDriver, IndexedDBDriver, and RemoteDriver. It supports file operations including listing, deleting, renaming, moving, archiving, and searching, and integrates with Uppy for uploads.

Tokens
56.1K
Snippets
162
Records
190
Agent score
68%

What's inside vuefinder

  1. What is VueFinder?

    master

    VueFinder is a modern, customizable file manager component designed for Vue 3. It provides a reactive, native-like file explorer interface that allows users to organize, preview, and manage files.

    Key characteristics include:

    • Backend-agnostic: It uses a driver-based architecture, meaning it can connect to any storage backend (Local, S3, PHP, Node.js, Python, etc.) without lock-in.
    • Rich Feature Set: Includes built-in text and image editors, multi-format previews (images, video, audio, PDF, text), deep recursive search, and ZIP archive management.
    • High Performance: Utilizes lazy loading for thumbnails and virtual columns for efficient rendering of large file lists.

  2. How search and navigation work in VueFinder

    master

    Search Functionality

    The search modal includes several advanced capabilities:

    • Sorting: Sort results by name, size, or date (asc/desc).
    • Folder Navigation: Double-clicking a folder result or selecting Open from the row menu navigates directly into that folder.
    • Pinning: Users can pin folders directly from search results to quickly access them later.
    • Request Cancellation: Rapid typing triggers an AbortController to cancel stale search requests, preventing old results from overwriting new ones.

    Navigation

    • Go to Folder: The Go menu provides a Go to Folder action with an autocomplete path-input modal. As you type, it suggests storage names and matching subfolders.

  3. How file previews work in VueFinder

    master

    VueFinder uses lazy-loaded renderers for different file types to keep the main bundle small.

    Text Preview (CodeMirror 6)

    Text files open in an editor with syntax highlighting, line numbers, and standard editor features (undo/redo, find, etc.).

    • Supported Languages: json, js, ts, tsx, jsx, vue, html, css, scss, md, yaml, xml.
    • Auto-detection: If a MIME type doesn't match the extension, VueFinder falls back to the file extension to determine the previewer (e.g., a .json file served as application/octet-stream will still open as text).

    Table View (CSV / TSV)

    .csv and .tsv files can be viewed as a table by clicking the Show as table checkbox in the preview panel.

    • Delimiters (,, ;, \t, |) are auto-detected.
    • Files larger than 1,000 rows show a preview note, though the full text is still available.

    Image Preview & Editor

    • Navigation: Supports zoom (mouse-wheel, +/-/0 keys) and panning (click-and-drag).
    • Editing: Includes a multi-tool editor for Crop, Rotate, Grayscale, and Adjust (brightness, contrast, saturation). Edited images are saved back through the driver via the save method.

  4. How VueFinder's driver-based architecture works

    master

    VueFinder uses a driver-based architecture to abstract file operations, allowing you to connect to different storage backends by implementing a common interface. This abstraction means the UI components remain the same regardless of whether you are using a remote HTTP API, in-memory arrays, or browser-based IndexedDB storage.

    VueFinder provides three built-in drivers:

    • RemoteDriver: For HTTP API backends (most common for production).
    • ArrayDriver: For in-memory file operations (useful for testing or demos).
    • IndexedDBDriver: For persistent browser-based storage (ideal for offline-first apps).

    You can also implement a custom driver by extending BaseAdapter and implementing the Driver interface.

    import { BaseAdapter, type Driver } from 'vuefinder';

class MyCustomDriver extends BaseAdapter implements Driver {
  async list(params?: ListParams): Promise<FsData> {
    // implementation
  }
  // ... other required methods
}

  5. Developer features and customization in VueFinder

    master

    VueFinder is designed for deep integration and customization via the following mechanisms:

    • Driver-based Architecture: Use local or remote drivers to connect to any storage backend.
    • Customizable Slots: Override UI elements like icons and the status bar.
    • Flexible Selection: Support for single or multiple selection with MIME type filtering.
    • Event Overrides: Custom event handlers to override default behaviors (e.g., double-click actions).
    • Feature System: A flexible system to enable or disable specific features as needed.
    • State Persistence: Optional localStorage persistence for user preferences.
    • Type Safety: Full TypeScript support with comprehensive type definitions.

  6. Create a unified custom menu bar by combining slots

    master

    You can merge the functionality of the menu, toolbar, and breadcrumb actions into a single custom bar by combining multiple slots and adjusting the VueFinder configuration:

    1. Use menu-items to define your menu.
    2. Use toolbar-items to define your toolbar.
    3. Use breadcrumb-actions to define your breadcrumb actions.
    4. Set showToolbar: false in your configuration to hide the default toolbar.
    5. Set showBreadcrumbBar: false if you do not need the path trail at all.

  8. Handle request cancellation with AbortSignal in custom drivers

    master

    Vuefinder supports request cancellation via the AbortSignal API. Several driver methods accept an optional signal?: AbortSignal parameter. This allows the UI (such as the search modal) to abort in-flight requests when a user performs actions like rapid typing or query invalidation.

    Methods that support cancellation:

    • list
    • search
    • getContent
    • save

    When implementing a custom driver, you should honor the signal by passing it to underlying asynchronous operations (like fetch) or by checking signal.aborted during long-running tasks to prevent late responses from overwriting current state.

  9. Handle File Selection in VueFinder

    master

    You can capture selected files using two different methods:

    Method 1: Using the select-button Prop

    Configure a selection button directly within the component using the :select-button prop. This prop accepts a configuration object:

    • active: Boolean indicating if the button is active.
    • multiple: Boolean to allow or disallow multiple file selection.
    • click: A callback function (items, event) => void triggered when the button is clicked. items contains the selected file objects.

    Method 2: Using the @select Event

    Listen for the @select event emitted by the <vue-finder> component. The event returns an array of selected items, which you can store in a local state variable.

    // Method 1: Select Button Config
const selectButtonConfig = {
  active: true,
  multiple: false,
  click: (items, event) => {
    if (!items.length) {
      alert('No item selected');
      return;
    }
    console.log('Selected:', items[0].path);
  },
};

// Method 2: Event Handler
const handleSelect = (selection) => {
  selectedFiles.value = selection;
};

  10. Understand Locale Prop Priority

    master

    When determining which language to display, VueFinder follows this priority order:

    1. The locale prop passed directly to the <vue-finder /> component.
    2. The cached locale stored in the global nanostores atom (which is persisted in localStorage).
    3. The default language (en).

    Passing a locale prop will override any previously saved user settings in localStorage.

  11. How archive and unarchive operations work

    master

    When performing archive or unarchive operations, VueFinder provides an inline, tree-based target folder picker.

    By default, the current folder is selected, but users can select a different destination. The destination path is sent as a destination field in the API call.

    Note: Backends must support the destination field; otherwise, they will default to the current folder.

  12. Use handler props instead of events

    master

    VueFinder supports two ways to handle lifecycle and interaction events: standard Vue event listeners (e.g., @select) and handler props (e.g., :on-select). Both methods are functionally identical.

    Example using events:

    <vue-finder @select="handleSelect" />

    Example using handler props:

    <vue-finder :on-select="handleSelect" />