File Browser

Installation

Import File Browser from the main package or its dedicated block entry. Import the shared styles and theme once.

import "@dicehub/kappa/styles/kappa.css";
import "@dicehub/kappa/styles/theme-kappa.css";
import { FileBrowser } from "@dicehub/kappa";
// Or: import { FileBrowser } from "@dicehub/kappa/blocks/file-browser";

Data and navigation

Use a flat items tree for local data. Each item requires a globally unique id, a name, and a kind of file or folder. Set parentId for children; omitted values belong to the null root. Optional metadata includes byte size, ISO modifiedAt, disabled, and readonly.

Activate a folder name to enter it. Breadcrumbs return to ancestors. Opening a file emits open(item) for the host to handle. Each navigation clears the filter and selection. Search applies to the current folder. Folders remain first in all sort orders; unknown sizes and dates sort as zero. Dates display in UTC.

Filtering preserves selected items outside the visible results; Select all affects only visible enabled items. readonly prevents rename and still permits opening and selection. The host defines custom action permissions.

Cards and folders

Set view="grid" for file-explorer cards. Add showView to let people switch between cards and the compact list. Use v-model:view when the host must store the choice.

<script setup>
import { ref } from "vue";
import { FileBrowser } from "@dicehub/kappa/blocks/file-browser";

const view = ref("grid");
const items = [
  { id: "docs", name: "Documents", kind: "folder" },
  { id: "images", name: "Images", kind: "folder" },
  { id: "readme", name: "README.md", kind: "file", size: 2400 },
];
</script>

<template>
  <FileBrowser
    v-model:view="view"
    :items="items"
    show-view
    title="Project files"
  />
</template>

Async loading

loadFolder(folderId, { signal }) returns direct children. It takes precedence over items and first runs after mount. The server renders a loading state. Return a fresh array after host mutations.

New requests abort old requests. Cancelled results are ignored even when the host ignores the signal. Errors show a retry action. The exposed refresh() method reloads the current folder. Breadcrumb navigation can cancel a pending folder load.

<script setup>
import { FileBrowser } from "@dicehub/kappa/blocks/file-browser";

async function loadFolder(folderId, { signal }) {
  const query = new URLSearchParams({ folder: folderId ?? "root" });
  const response = await fetch(`/api/files?${query}`, { signal });
  if (!response.ok) throw new Error("Files could not be loaded.");
  return response.json(); // Direct child FileBrowserItem records.
}
</script>

<template>
  <FileBrowser :load-folder="loadFolder" title="Project files" />
</template>

Rename and new folders

Provide renameItem and createFolder to enable their controls. The host changes its data or remote storage. Callbacks receive the current folderId and an AbortSignal. Resolve on success or reject with a safe, user-facing Error message.

Names are trimmed. Empty names, path separators, control characters, dot segments, and exact duplicate names are rejected locally. Other rules belong to the host. Failed requests keep the dialog open. While saving, dismissal and duplicate submissions are disabled. Success refreshes the folder, closes the dialog, and returns focus to an enabled control.

<script setup>
import { ref } from "vue";
import { FileBrowser } from "@dicehub/kappa/blocks/file-browser";

const items = ref([
  { id: "notes", name: "notes.md", kind: "file", size: 800 },
]);
function renameItem(item, name) {
  items.value = items.value.map(value => value.id === item.id ? { ...value, name } : value);
}
function createFolder(name, { folderId }) {
  items.value.push({ id: crypto.randomUUID(), name, kind: "folder", parentId: folderId });
}
</script>

<template>
  <FileBrowser :items="items" :rename-item="renameItem" :create-folder="createFolder" />
</template>

Host actions

actions(item) returns menu entries with id, label, and optional disabled or destructive. runAction(id, item, context) performs the work. The host supplies any needed confirmation. Errors appear above the list; success refreshes the current folder.

Each item exposes the same actions through its menu button and the Kappa Context Menu. Right-click an item, or focus it and press Shift+F10. Right-click empty space to create a folder or refresh when those operations are available.

<FileBrowser
  :items="items"
  :actions="item => [{ id: 'details', label: 'Show details' }]"
  :run-action="async (action, item, { signal }) => { await showDetails(item, signal); }"
  @open="openFile"
>
  <template #selection="{ items: selected, clear }">
    <Button size="sm" @click="attachFiles(selected); clear()">Attach selected files</Button>
  </template>
</FileBrowser>

The actions slot adds header controls and receives folderId and refresh. The selection slot receives selected items and clear. The icon slot receives the row item. Host controls must respect permissions and pending work.

Accessibility

Kappa Breadcrumbs, Filter Bar, Table, Checkbox, Dropdown, Context Menu, and Dialog Layout provide the controls. Menus and dialogs follow Ark UI Menu and Ark UI Dialog. Dialog dismissal is blocked during saving.

Tab reaches file names, checkboxes, and menus. Enter or Space activates a file or folder. Navigation moves focus to a stable content region when focus was inside the browser. The table scroll area is also focusable. Loading, counts, and errors are announced. Small screens hide modified dates and keep the table inside a horizontal scroll area.

Translate labels and filterLabels, including actions(name), select(name), count(count), and selected(count). Theme tokens supply both modes. The block adds no motion.

API Reference

Events: update:modelValue(string[]), update:view("list" | "grid"), open(item), navigate(location[]), and complete({ operation, folderId, item?, action? }). Operations are rename, create, or action.

FileBrowser, FileBrowser.Root, and FileBrowserRoot expose the same block. FILE_BROWSER_DEFAULT_LABELS and all FileBrowser* data, prop, event, and slot interfaces are public exports. HTML attributes and listeners pass to the root section.

The root exposes data-slot="file-browser" and data-state="loading|error|ready|empty". --kappa-file-browser-max-height changes the default 28rem content height.

File Browser displays one complete folder listing. It does not provide uploads, previews, pagination, virtual scrolling, drag-and-drop, or storage access. Integrate these through host controls when required. Use bounded folder results for large data sets.