# StoragePicker — SvelteKit UI

Package: sveltekit-ui 1.1.94

Page: https://www.sveltekit-ui.com/components/storage_picker

Category: Input controls

Selects local files or application-provided storage records, with folders, previews, grid/list views, and optional multiple selection.

Public component import: `StoragePicker`

Public manager import: `create_storage_picker_manager`

## Component notes

- notes:
  - The picker does not list files from a service or upload them automatically. Supply authorized storage metadata and serve GET storage_src URLs from your backend. File reading, fetching, and object URLs happen in the browser.
  - StoragePicker cleans up requests and owned object URLs when destroyed. Do not retain its temporary preview URLs as persistent storage URLs.

## Usage

```svelte
<script>
  // Import the shared stylesheet once in your application's root layout.
  import "sveltekit-ui/style.css"
  import { StoragePicker, create_storage_picker_manager } from "sveltekit-ui"

  let chosen_files = $state([])

  const manager = create_storage_picker_manager({
    // Only the local-file section is enabled; this example needs no backend.
    storage_origins: ["locally_uploaded_files"],
    accept: ["image/*", ".pdf", "text/plain"],
    is_multiselect: true,
    max_selected_files: 3,
    view_mode: "list",
    on_finish: (value) => { chosen_files = value ?? [] },
  })
</script>

<StoragePicker {manager} />
<p role="status">{chosen_files.length} files selected. Files stay in this example until you upload them through your own backend.</p>
```

## Configuration

### `storage`

- type: object | array | function
- default: null
- description: Storage records keyed by id, or an array of records with ids. Each record uses { id, file_name, mime_type, folder_path?: string[], file_extension?, size_kb?, src?, base64_content? }. A callback is read during initialization.

### `locally_uploaded_files`

- type: object | array | function
- default: null
- description: Initial local-file collection keyed by id or an array. Records may contain a browser File in file plus name/MIME metadata; selecting prepares base64_content.

### `val`

- type: object | array | null | function
- default: null
- description: Initial selected record (single mode) or record array (multiple mode). Setting records without base64_content or file fetches their id through storage_src.

### `storage_src`

- type: string | function
- default: /api/storage/{storage_id}
- description: URL template whose {storage_id} placeholder is replaced by the selected record id. A direct record src can provide a preview, but selection still uses this template unless file/base64_content is supplied.

### `storage_origins`

- type: array | function
- default:
  - locally_uploaded_files
  - storage
- allowed_values:
  - locally_uploaded_files
  - storage
- description: Enabled picker sections. Use ['locally_uploaded_files'] for a local-only picker that needs no storage backend.

### `default_folder_path`

- type: array | function
- default:
- description: Initial folder path as string segments, such as ['documents', 'reports'].

### `accept`

- type: array | function
- default: null
- description: Accepted MIME strings, wildcard groups, or dotted extensions: ['image/*', 'application/pdf', '.txt']. Empty/null accepts all. Client filtering does not replace server validation.

### `is_multiselect`

- type: boolean | function
- default: false
- description: Allow multiple selected records and a Finish action.

### `max_selected_files`

- type: number | null | function
- default: null
- description: Selection limit; nonnegative values are floored to integers. null means unlimited.

### `is_show_content`

- type: boolean | function
- default: true
- description: Show previews/metadata of the current selection below the trigger.

### `is_show_button`

- type: boolean | function
- default: true
- description: Show the Select File(s) trigger. Use open_popover() from your own action if hidden.

### `is_disabled`

- type: boolean | function
- default: false
- description: Disable selection and local-file actions.

### `is_read_only`

- type: boolean | function
- default: false
- description: Disable edits while retaining the current selected-file display.

### `view_mode`

- type: string | function
- default: grid
- allowed_values:
  - grid
  - list
- description: Initial file view mode.

### `is_show_file_view_toggle`

- type: boolean | function
- default: true
- description: Show grid/list controls when files exist.

### `display_height`

- type: number | function
- default: 20
- description: Preview tile height in rem.

### `mt`

- type: number | function
- default: 0
- description: Top margin in rem.

### `mb`

- type: number | function
- default: 0
- description: Bottom margin in rem.

### `on_finish`

- type: function
- description: Receives a prepared record in single mode, an array after Finish in multiple mode, or null after clear(). Selected records include raw base64_content. Implement upload/persistence in your application's backend.

## Methods

### `init()`

- parameters:
  - config: picker configuration
- returns: void
- description: Initialize file collections, folder state, and child managers. Prefer a new manager when replacing the configuration.

### `open_popover()`

- returns: void
- description: Refresh file controls and open the picker unless disabled.

### `set_val()`

- parameters:
  - input: record | record[] | null
- returns: Promise<void>
- description: Prepare and set selected files, aborting prior work. Errors set error_message; does not call on_finish.

### `select_file()`

- parameters:
  - storage_item: file record
  - loading_id: string (optional)
- returns: Promise<boolean>
- description: Select a prepared/fetched record or toggle it in multiple mode. In single mode calls on_finish and closes. Respects disabled state and selection limit; false indicates failure or skipped action.

### `toggle_select_all_locally_uploaded_files()`

- returns: Promise<boolean>
- description: Select available local files up to the limit, or deselect all local files if all are selected.

### `clear()`

- parameters:
  - is_call_finish: boolean = true
- returns: void
- description: Abort pending work, clear selection/previews, and normally emit null through on_finish.

### `set_view_mode()`

- parameters:
  - input: 'grid' | 'list'
- returns: void
- description: Change file presentation; ignores other values.

### `set_files_prepped()`

- returns: void
- description: Rebuild folder and file controls for current folder/filter state.

### `is_item_accepted()`

- parameters:
  - storage_item: file record
  - accepted_types: array (default acceptable_mime_types)
- returns: boolean
- description: Match a file's MIME type/extension against the supplied accept filter.

### `get_ordered_items()`

- parameters:
  - storage: records by id
  - locally_uploaded_files: records by id
  - storage_path: string[]
  - acceptable_mime_types: array | null
- returns: object
- description: Return { folder_ids, storage_ids, locally_uploaded_files_ids } filtered to enabled origins, folder path, and acceptable file types.

### `on_destroy()`

- returns: void
- description: Abort pending work and revoke owned URLs. Called automatically by StoragePicker on destruction.

## Returned state

### `id`

- type: string
- description: Unique manager id.

### `val`

- type: object | array | null
- description: Current prepared selection, including base64_content for selected files.

### `storage`

- type: object | null
- description: Storage collection normalized to records keyed by id.

### `locally_uploaded_files`

- type: object | null
- description: Current local-file records keyed by id.

### `storage_path`

- type: array
- description: Current folder segments.

### `default_folder_path`

- type: array
- description: Initial folder segments.

### `storage_origins`

- type: array
- description: Enabled storage sources.

### `display_file`

- type: object | array | null
- description: Prepared display records with preview source and any embedded media manager.

### `error_message`

- type: string | null
- description: Most recent selection or file-reading error.

### `acceptable_mime_types`

- type: array | null
- description: Current accept filter.

### `ordered_items`

- type: object
- description: Current visible folder, stored-file, and local-file ids.

### `locally_uploaded_files_prepped`

- type: array
- description: Local records with preview and selection child managers.

### `storage_files_prepped`

- type: array
- description: Stored-file records with preview and selection child managers.

### `folders_prepped`

- type: array
- description: Folder navigation Button managers.

### `view_mode`

- type: string
- description: Current grid/list presentation.

### `display_height`

- type: number
- description: Preview tile height in rem.

### `max_selected_files`

- type: number | null
- description: Normalized selection limit.

### `are_all_locally_uploaded_files_selected`

- type: boolean
- description: Whether every currently filtered local file is selected.

### `is_show_content`

- type: boolean
- description: Current picker UI state.

### `is_multiselect`

- type: boolean
- description: Current picker UI state.

### `is_disabled`

- type: boolean
- description: Current picker UI state.

### `is_read_only`

- type: boolean
- description: Current picker UI state.

### `is_file_chosen`

- type: boolean
- description: Current picker UI state.

### `is_show_button`

- type: boolean
- description: Current picker UI state.

### `is_show_select_all_locally_uploaded_files`

- type: boolean
- description: Current picker UI state.

### `is_show_file_view_controls`

- type: boolean
- description: Current picker UI state.

### `mt`

- type: number
- description: Top margin in rem.

### `mb`

- type: number
- description: Bottom margin in rem.

### `breadcrumbs_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `popover_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `file_input_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `select_file_from_storage_button_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `clear_button_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `finish_multiselect_button_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `file_icon_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `list_file_icon_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `grid_view_button_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `list_view_button_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.

### `select_all_locally_uploaded_files_button_manager`

- type: object
- description: Child UI manager rendered by StoragePicker.
