https://www.npmjs.com/package/octopus-file-browser

octopus-file-browser

A responsive, framework-free file browser inspired by Gitea. It ships as an accessible Web Component with Material Icon Theme icons and no runtime dependencies.

Install

npm install octopus-file-browser

Use

<octopus-file-browser empty-label="No files"></octopus-file-browser>

<script type="module">
  import 'octopus-file-browser';

  const browser = document.querySelector('octopus-file-browser');

  async function open(path) {
    const response = await fetch(`/api/ls?path=${encodeURIComponent('/' + path.join('/'))}`);
    const entries = await response.json();
    browser.path = path;
    browser.entries = entries;
  }

  browser.addEventListener('octopus:navigate', ({ detail }) => open(detail.path));
  browser.addEventListener('octopus:open', ({ detail }) => console.log(detail.path, detail.entry));

  open([]);
</script>

Importing the package registers <octopus-file-browser>. The browser displays one directory at a time: your app sets path and that directory's entries. Selecting a directory or .. emits octopus:navigate with the requested path, and your app loads that directory and sets both again. Selecting a file emits octopus:open.

Entry data

| Field | Type | Description | | --- | --- | --- | | name | string | Displayed filename. | | type | "file" \| "directory" | Entry kind. | | size | number | File size in bytes. | | modified | Date \| string \| number | Modified time. | | icon | string | Optional custom icon URL. |

Directories are sorted before files. Names use natural, case-insensitive sorting.

API

| API | Description | | --- | --- | | browser.entries | Gets or replaces the current directory's entries. | | browser.path | Gets or sets the current directory path, for example ['home', 'ubuntu']. .. is shown when it is not empty. | | browser.contextMenu | Gets or sets the context menu items. Empty by default. | | empty-label | Attribute controlling the empty-directory message. | | octopus:open | Event with { entry, path } when a file is selected. | | octopus:navigate | Event with { path } when a directory or .. is selected. The browser does not change until your app sets path and entries. |

The package also exports OctopusFileBrowser, createOctopusFileBrowser, sortEntries, formatFileSize, formatRelativeDate, isRecent, and fileKindLabel. Type declarations are included.

Context menu

The context menu is off until you set items. Right-click, the Menu key, or a touch long press on a file or directory opens it.

browser.contextMenu = [
  { label: 'Copy path', action: (entry, path) => navigator.clipboard.writeText('/' + path.join('/')) },
  { label: 'New folder…', when: (entry) => entry.type === 'directory', action: (entry, path) => createFolder(path) },
  { label: 'Download', when: (entry) => entry.type === 'file', action: (entry, path) => download(path) },
  { label: 'Validate JSON', when: (entry) => entry.name.endsWith('.json'), action: (entry, path) => validate(path) },
  { label: 'Delete', danger: true, action: (entry, path) => remove(path) },
];

| Field | Type | Description | | --- | --- | --- | | label | string | Menu item text. | | action | (entry, path) => void | Called when the item is selected. | | when | (entry, path) => boolean | Optional. Shows the item only for entries it returns true for. Items without when show for every entry. | | danger | boolean | Optional. Styles the item as destructive. |

Items appear in the order given. When no item matches an entry, the native context menu is shown instead.

Theme

Set CSS custom properties on the element:

octopus-file-browser {
  --ofb-border: #d0d7de;
  --ofb-text: #181c21;
  --ofb-muted: #57606a;
  --ofb-link: #1f2328;
  --ofb-hover: #f6f8fa;
  --ofb-focus: #0969da;
  --ofb-recent: #d15700;
  --ofb-danger: #cf222e;
}

Repository outputs

• dist/ contains the publishable ESM and UMD/CJS library builds.
• demo/ is the static demo and can be used as a Cloudflare Pages output directory.
• npm run check runs tests and rebuilds both outputs.

See LICENSE and THIRD_PARTY_NOTICES.