feat: add directory browsing and selection to knowledge pickers

[silentoplayz]

Pull Request Checklist

Note to first-time contributors: Please open a discussion post in Discussions to discuss your idea/fix with the community before creating a pull request, and describe your changes before submitting a pull request.

This is to ensure large feature PRs are discussed with the community first, before starting work on it. If the community does not want this feature or it is not relevant for Open WebUI as a project, it can be identified in the discussion before working on the feature and submitting the PR. For bug fixes referencing an existing Issue, linking the Issue is sufficient.

Before submitting, make sure you've checked the following:

• Linked Issue/Discussion: This PR references an existing Issue or Discussion — Closes #___ / Relates to #___. If one does not exist, create one first. PRs without a linked issue or discussion may be closed without review.
• Target branch: The pull request targets the dev branch. PRs targeting main will be immediately closed.
• Description: A concise description of the changes is provided below.
• Changelog: A changelog entry following Keep a Changelog format is included at the bottom.
• Documentation: Relevant documentation has been added or updated in the Open WebUI Docs Repository.
• Dependencies: Any new or updated dependencies are explained, tested, and documented.
• Testing: Manual tests have been performed to verify the fix/feature works correctly and does not introduce regressions. Screenshots or recordings are included where applicable.
• No Unchecked AI Code: This PR is either human-written or has undergone thorough human review AND manual testing. Unreviewed AI-generated PRs may be closed immediately.
• Self-Review: A self-review of the code has been performed, ensuring adherence to project coding standards.
• Architecture: Smart defaults are preferred over new settings. Local state is used for ephemeral UI logic. Major architectural or UX changes have been discussed first.
• Git Hygiene: The PR is atomic (one logical change), rebased on dev, and contains no unrelated commits.
• Title Prefix: The PR title uses one of the following prefixes:
  • BREAKING CHANGE: Changes affecting backward compatibility
  • build: Build system or dependency changes
  • ci: CI/CD workflow changes
  • chore: Refactoring, cleanup, or non-functional changes
  • docs: Documentation additions or updates
  • feat: New features or enhancements
  • fix: Bug fixes or corrections
  • i18n: Internationalization or localization changes
  • perf: Performance improvements
  • refactor: Code restructuring
  • style: Formatting changes (whitespace, semicolons, etc.)
  • test: Test additions or corrections
  • WIP: Work in progress

---

Summary

Open WebUI supports organizing files within knowledge bases into directories, but this directory structure was invisible in every knowledge picker UI — the # command dropdown, the Attach Knowledge (+ button) menu, and the model editor knowledge selector all displayed a flat list of files. Users had no way to navigate, browse, or select a specific directory when attaching knowledge to a chat or model.

This PR surfaces the existing directory structure in all three knowledge picker UIs by leveraging the searchKnowledgeFilesById API's existing directoryId parameter — no backend changes required.

Why this matters

• Discoverability: Knowledge bases with many files organized into directories are now navigable instead of an overwhelming flat list
• Precision: Users can attach a specific directory's files as context rather than the entire knowledge base, leading to more focused and relevant model responses
• Consistency: All three knowledge pickers now share the same browsing interaction pattern — users learn one paradigm

Approach

The core idea is simple: instead of calling searchKnowledgeFilesById without a directoryId (which returns every file in the KB flat), pass directoryId to scope results to a specific level. The API already returns directories, breadcrumbs, and items in its response — the frontend was simply ignoring the first two.

Each modified component adds:

1. Browsing state (browsingCollection, currentDirectoryId, browsingBreadcrumbs, etc.) — local component state tracking where the user is navigating
2. Navigation functions (browseIntoCollection, browseIntoDirectory, navigateBack) — drive the browsing state and re-fetch scoped results
3. Directory selection (selectDirectory) — fetches all files directly in a directory and attaches them individually as chat context
4. Updated template — renders directories with folder icons above files, breadcrumb navigation with back arrow, and + buttons for both "select entire collection" and "select directory"

Interaction changes

Element	Before	After
Collection row (all pickers)	Click → immediately selects entire collection	Click → navigates into the collection to browse its structure
Collection "select all"	N/A (was the only behavior)	+ button on the right side of the row selects the entire collection
Directories	Not visible anywhere	Shown with 📁 folder icon, click to navigate into, + to select all files
Files inside a KB	Flat list of everything	Scoped to current directory level
Navigation	None	Back arrow + clickable breadcrumb path segments

Files Changed (5)

src/lib/components/chat/MessageInput/Commands/Knowledge.svelte

The # command dropdown — the most-used knowledge picker. Added full browsing state, navigation logic, and a two-mode template (top-level flat view vs. browsing view). Collections now show a chevron and + button; clicking navigates in. The browsing view renders a header with back/breadcrumbs/select-all, then directories grouped above files.

src/lib/components/chat/MessageInput/CommandSuggestionList.svelte

Handles the onSelect callback from the # command Knowledge component. Added a new knowledge-directory event type handler that iterates through all resolved files and calls onUpload for each one — enabling batch attachment of an entire directory's files.

src/lib/components/chat/MessageInput/InputMenu/Knowledge.svelte

The Attach Knowledge panel (via + button). Previously called searchKnowledgeFilesById without a directoryId, resulting in a flat file dump. Now passes currentDirectoryId to scope results, tracks selectedFileDirectories and selectedFileBreadcrumbs from the response, and renders directories with navigation and selection above the file list within each expanded KB.

src/lib/components/workspace/Models/Knowledge/KnowledgeSelector.svelte

The knowledge picker dropdown in the model editor (used for both base and workspace models). Same pattern as the # command dropdown, adapted for the Dropdown component and createEventDispatcher pattern. Collections are now browsable; directories appear with navigation and selection. Browsing state resets when the dropdown closes.

src/lib/components/workspace/Models/Knowledge.svelte

The parent wrapper that consumes KnowledgeSelector events. Added a null guard (selectedItems ?? []) to the on:select handler to prevent TypeError: can't access property "find" when selectDirectory dispatches multiple select events — the Svelte 5 runtime's prop getter can return undefined before the reactive initializer runs.

Key design decisions

1. No backend changes: The searchKnowledgeFilesById API already supports directoryId filtering and returns directories/breadcrumbs in every response. All changes are frontend-only.

2. Non-recursive directory selection: Selecting a directory attaches only files directly within it, not files in nested subdirectories. This gives users precise control — they can navigate deeper and select subdirectories individually.

3. Collection click behavior change: Clicking a collection row now navigates into it instead of immediately selecting it. The old "select entire collection" behavior is preserved via a + button. This tradeoff favors browsability (the common case when you have directories) while keeping immediate selection one click away.

4. All strings wrapped in $i18n.t(): New user-facing strings ('Directories', 'This directory is empty.', 'Select directory', 'Select collection', 'Directory') are all i18n-ready.

This PR was prepared with AI copilot assistance and has been thoroughly reviewed and manually tested by the author.

Changelog Entry

Description

• Add directory browsing and selection support to all three knowledge picker UIs (# command dropdown, Attach Knowledge menu, model editor knowledge selector), allowing users to navigate into knowledge base directory structures, browse files at each level, and selectively attach individual files or entire directories as context

Added

• Directory navigation UI in the # command dropdown with back button, breadcrumb trail, and directory/file listing
• Directory navigation UI in the Attach Knowledge (+ button) menu within expanded knowledge bases
• Directory navigation UI in the model editor KnowledgeSelector dropdown
• knowledge-directory event type in CommandSuggestionList for batch file attachment from directory selection
• + button on collection and directory rows for quick selection without navigating into them

Fixed

• Null guard for selectedItems in the model editor knowledge wrapper to prevent TypeError when selecting directories (Svelte 5 runtime prop getter edge case)

---

Additional Information

• Zero new dependencies — all changes use existing APIs and icon components
• The searchKnowledgeFilesById API already returned directories and breadcrumbs in its response; the frontend was simply not using them
• All UI changes follow existing design patterns: same Tailwind classes, icon components (Folder, ArrowLeft, ChevronRight, Plus), Tooltip wrapping, and hover/dark-mode styling as the rest of the codebase
• Closes/Relates to feat: Show knowledge base folder structure when attaching knowledge in a chat #27011

Screenshots or Videos

# Command Dropdown

Before	After

Attach Knowledge (+ Button) Menu

Before	After

Model Editor Knowledge Selector

Before	After

Manual Verification Performed

1. # command dropdown: Typed # in chat input → verified collections show chevron → clicked collection → saw directories and files at root level → navigated into a directory → verified breadcrumbs update → clicked back arrow → returned to root → clicked + on a directory → verified all files in that directory attached to chat → clicked + on header → verified entire collection selected
2. Attach Knowledge menu: Clicked + → Knowledge → expanded a KB → verified directories appear above files → clicked a directory → navigated in with breadcrumbs → clicked a file → verified it attached → used + on a directory → verified batch attachment
3. Model editor knowledge picker: Opened model editor → clicked "Select Knowledge" → verified collections show browse-in behavior → navigated into a collection → browsed directories → selected a directory via + → verified all files added to model knowledge without errors
4. Regression: Verified folders (chat folders), notes, files, YouTube URLs, and web URLs all still work correctly in the # dropdown with no behavioral changes

Contributor License Agreement

• By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.

Note

Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.

[spencerthayer]

@silentoplayz I've already merged your calendar fix into my fork, please let me know when you've fixed this PR. I would love to merge this into my personal fork.

[silentoplayz]

@silentoplayz I've already merged your calendar fix into my fork, please let me know when you've fixed this PR. I would love to merge this into my personal fork.

This PR isn't broken in any way AFAIK and there aren't any merge conflicts against the dev branch. It's only open as a draft PR because I exceeded a limit of 5 open PRs before the restriction was put in place by the repo maintainer.

[owui-terminator]

Notice regarding PR context

@silentoplayz

This pull request does not link to a related issue or discussion.

Please add a relevant GitHub issue/discussion reference, such as #123 or a full /issues/123 or /discussions/123 URL. If there is no issue or discussion to link, reply here with a short explanation of the change and why it is needed, then reopen the pull request.

This pull request has been closed.

[silentoplayz]

Rebased on the latest dev. All merge conflicts are resolved and the browsing UI has been updated to match the recent UI refactors in the knowledge pickers. Builds clean and re-tested locally.

[spencerthayer]

Thanks @silentoplayz I'll be sure to grab your changes for my fork.

[silentoplayz]

This PR has yet again been rebased on the latest dev. All new merge conflicts have been resolved and the browsing UI has been updated to match the recent UI refactors in the knowledge pickers. Builds clean and re-tested locally.