feat(ui.file_browser): add flexible path_filter support

[tsubasakong]

📝 Summary

Closes #8399

• add an optional path_filter parameter to mo.ui.file_browser
• support glob strings (e.g. "data_*.csv") and callable filters (Callable[[Path], bool])
• keep existing filetypes behavior and combine it with path_filter using AND logic
• apply path_filter to directories in selection_mode="directory"
• add coverage for glob, callable, directory-mode filtering, and invalid filter validation

🔍 Description of Changes

• add an optional path_filter parameter to mo.ui.file_browser
• support glob strings (e.g. "data_*.csv") and callable filters (Callable[[Path], bool])
• keep existing filetypes behavior and combine it with path_filter using AND logic
• apply path_filter to directories in selection_mode="directory"
• add coverage for glob, callable, directory-mode filtering, and invalid filter validation

Validation:

• python3 -m compileall marimo/_plugins/ui/_impl/file_browser.py tests/_plugins/ui/_impl/test_file_browser.py

Closes #8399

📋 Checklist

• I have read the contributor guidelines.
• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
• Tests have been added for the changes made.
• Documentation has been updated where applicable, including docstrings for API changes.
• Pull request title is a good summary of the changes - it will be used in the release notes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Mar 13, 2026 4:55am

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[tsubasakong]

I have read the CLA Document and I hereby sign the CLA

[tsubasakong]

recheck

[Copilot]

Pull request overview

Adds flexible path_filter support to mo.ui.file_browser, enabling additional filtering via glob patterns or callables while preserving existing filetypes behavior and adding tests to validate the new functionality.

Changes:

• Added optional path_filter parameter (glob string or Callable[[Path], bool]) and applied it during directory listing.
• Combined filetypes filtering with path_filter using AND logic, and applied path_filter to directories in selection_mode="directory".
• Added tests for glob filtering, callable filtering, directory-mode filtering, and invalid filter validation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
marimo/_plugins/ui/_impl/file_browser.py	Introduces path_filter type/validation and integrates it into listing + recursive empty-dir checks.
tests/_plugins/ui/_impl/test_file_browser.py	Adds coverage for glob/callable filters, directory-mode behavior, and invalid path_filter inputs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_has_files_recursive now applies path_filter (via _matches_file_filters) in addition to filetypes when determining whether a directory is “empty”. The surrounding documentation/comments currently describe only filetype-based filtering (e.g., in the ignore_empty_dirs doc text). Please update the relevant docstrings/comments to reflect that both filetypes and path_filter are applied during recursive emptiness checks, so the behavior is not surprising to users.

[Copilot]

If a user-provided callable path_filter raises (e.g., due to transient filesystem errors like stat() failing), the exception will bubble up and likely produce a low-context error originating from inside the filter. Consider wrapping callable execution in a try/except and re-raising with a higher-context message that includes the path being evaluated and indicates the failure came from path_filter (optionally chaining the original exception). This makes runtime failures significantly easier to diagnose.

Suggested change

	return bool(self._path_filter(path))
	try:
	result = self._path_filter(path)
	except Exception as exc:
	raise RuntimeError(
	f"path_filter callable raised an exception for path {path!r}"
	) from exc
	return bool(result)

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

marimo/_plugins/ui/_impl/file_browser.py:140

• The new path_filter is described as an additional filter, but ignore_empty_dirs uses _has_files_recursive() which now applies _matches_file_filters() (and therefore path_filter) when deciding whether a directory is “empty”. Either document this interaction here (so users understand that ignore_empty_dirs=True is based on the filtered view), or adjust the recursive emptiness check if the intent is to only consider filetypes.

        path_filter (Union[str, Callable[[Path], bool]], optional): Additional
            path-based filtering to apply. In file mode, this is applied to files;
            in directory mode, this is applied to directories. If a string is
            provided, it is treated as a glob pattern (for example, "data_*.csv").
            If a callable is provided, it should return True for paths that should
            be included. Defaults to None.
        selection_mode (Literal["file", "directory"], optional): Either "file" or "directory". Defaults to
            "file".
        multiple (bool, optional): If True, allow the user to select multiple
            files. Defaults to True.
        restrict_navigation (bool, optional): If True, prevent the user from
            navigating any level above the given path. Defaults to False.
        ignore_empty_dirs (bool, optional): If True, hide directories that contain
            no files (recursively). Directories are scanned up to 100 levels deep
            to prevent stack overflow from deeply nested structures. Directory
            symlinks are skipped during traversal to prevent infinite loops.
            Filetype filtering is applied recursively and is case-insensitive.
            This may impact performance for large directory trees. Defaults to False.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.