{"id":15489336,"url":"https://github.com/igorskyflyer/npm-vscode-folderpicker","last_synced_at":"2025-04-22T18:20:19.986Z","repository":{"id":45823831,"uuid":"384088830","full_name":"igorskyflyer/npm-vscode-folderpicker","owner":"igorskyflyer","description":"✨ Provides a custom Folder Picker API + UI for Visual Studio Code. 🎨","archived":false,"fork":false,"pushed_at":"2023-05-03T22:58:06.000Z","size":2113,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T17:35:51.289Z","etag":null,"topics":["back-end","igorskyflyer","javascript","module","node","npm","visual-studio-code","vscode","vscode-api","vscode-extension"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@igor.dvlpr/vscode-folderpicker","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igorskyflyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-08T10:35:54.000Z","updated_at":"2022-10-20T18:32:29.000Z","dependencies_parsed_at":"2024-11-15T20:02:24.994Z","dependency_job_id":"4acca66a-109b-427a-aab1-ec3137848bcc","html_url":"https://github.com/igorskyflyer/npm-vscode-folderpicker","commit_stats":{"total_commits":82,"total_committers":1,"mean_commits":82.0,"dds":0.0,"last_synced_commit":"b358b3271a6d18119918a6b6d7e0228000f5996c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-vscode-folderpicker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-vscode-folderpicker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-vscode-folderpicker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fnpm-vscode-folderpicker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorskyflyer","download_url":"https://codeload.github.com/igorskyflyer/npm-vscode-folderpicker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249598186,"owners_count":21297464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["back-end","igorskyflyer","javascript","module","node","npm","visual-studio-code","vscode","vscode-api","vscode-extension"],"created_at":"2024-10-02T07:05:05.188Z","updated_at":"2025-04-22T18:20:19.966Z","avatar_url":"https://github.com/igorskyflyer.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## FolderPicker\n\n\u003csub\u003e\u003cem\u003efor Visual Studio Code\u003c/em\u003e\u003c/sub\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003eMade possible with 🦎 \u003cem\u003eGecko\u003c/em\u003e - an upcoming project.\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003e ⚠ This module is built as the core functionality of my **[New Folder](https://github.com/igorskyflyer/vscode-new-folder)** Visual Studio Code extension and is still under active development, use at own risk, if needed.\n\n\u003cbr\u003e\n\n\u003e ✨ Current major version `v.2.x.x` contains breaking changes.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\nProvides a custom Folder Picker API + UI for Visual Studio Code.\n\n\u003cbr\u003e\n\nThe module exposes a single function `showFolderPicker()` which provides a custom `QuickPick` UI rather than the _built-in_ Visual Studio Code `QuickPick` UI.\n\n\u003cbr\u003e\n\nCurrently, its functionalities are tightly-coupled with my extension **[New Folder](https://github.com/igorskyflyer/vscode-new-folder)** but I will make the module more generic in the future.\n\n\u003cbr\u003e\n\n\u003e 🙋‍♂️ The necessity for this module?\n\n\u003e 💬 When I started my beforementioned **[New Folder](https://github.com/igorskyflyer/vscode-new-folder)** extension for Visual Studio Code my goal was to implement a simple UX for creating new folders when opening a new/blank instance of Visual Studio Code since that behavior is not built-in. I started with the built-in [`vscode.window.showSaveDialog()`](https://code.visualstudio.com/api/references/vscode-api) function which works great when you set the option `files.simpleDialog.enable` to `true` but that is a global preference and not everyone - including myself - wants to change the whole UX for file/folder opening just for that. Then I reached out to our friends at [@microsoft/vscode](https://github.com/microsoft/vscode) and posted a feature request [#127201](https://github.com/microsoft/vscode/issues/127201) to override this behavior but they closed the feature request as that is by-design. Another issue that was present is that the original code only allowed to create a single-level child folder (no nested/recursive folder creation) due to limitations of the native `vscode.window.showSaveDialog()` function. Upon closure I decided to build my own UI/logic for that and this project and module are what I managed to achieve so far. 🤗\n\n\u003cbr\u003e\n\n### Usage\n\nInstall it by running\n\n```shell\nnpm i \"@igor.dvlpr/vscode-folderpicker\"\n```\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n### API\n\n\u003cbr\u003e\n\n\u003ca id=\"folder-picker-responsespeed\"\u003e\u003c/a\u003e\n\n```ts\nenum ResponseSpeed\n```\n\nUsed for controlling the response speed of the `InputBox` of the `QuickPick`. Since `v.2.0.0` callbacks for generating Actions are throttled/debounced when necessary and the picker now waits for the user to finish their input before generating available Actions for performance reasons. Throttling provided by [`Zep()`](https://www.npmjs.com/package/@igor.dvlpr/zep).\n\nAvailable values are: `Instant`, `Fast`, `Normal` (default), `Lazy`.\n\nNote: setting the property `responseSpeed` in the `options` parameter of `showFolderPicker()` to `Instant` will disable throttling!\n\n\u003cbr\u003e\n\n```ts\nshowFolderPicker(directory: string, options?: FolderPickerOptions): void\n```\n\n**Parameters**\n\n_directory_: `string` - the initial directory to show in Folder Picker UI, if none is specified default to user home directory,\n_options_: `FolderPickerOptions` - additional options to pass and where you should place your callbacks, will most likely change in the near future. All properties are **optional** and callbacks are not defined.\n\nAvailable properties/callbacks:\n\n`FolderPickerOptions`\n\n- **`[dialogTitle]`**: **string** = **'Pick a Folder'** - the Folder Picker title, shown at the top of the picker,\n\n- **`[showIcons]`**: **boolean** = **true** - indicates whether icons will be shown in the Folder Picker. When this property is set to `false` all/any icons you set will be ignored,\n\nIcons - grouped together for brevity\n\n- **`[iconFolder]`**: **string** = '' - _icon_ to use for folder entries,\n- **`[iconFolderUp]`**: **string** = '' - _icon_ to use for the folder up entry,\n- **`[iconCreate]`**: **string** = '' - _icon_ to use for `Create folder` Action,\n- **`[iconNavigate]`**: **string** = '' - _icon_ to use for `Navigate to...` Action,\n- **`[iconPick]`**: **string** = '' - _icon_ to use for `Pick current directory` Action.\n- **`[iconClear]`**: **string** = '' - _icon_ to use for `Clear` Action, available when the folder name is not valid.\n\nBe aware that the term _icon_ is used here as a descriptive one, this property expects a **single** emoji or a **single** `ThemeIcon` which is a string as well, to see the list of available ThemeIcons, look at the official Visual Studio Code documentation, **[here](https://code.visualstudio.com/api/references/icons-in-labels#icon-listing)**,\n\n- **`[responseSpeed]`**: **ResponseSpeed** = **ResponseSpeed.Normal** - used for controlling the response speed of the `InputBox` of the `QuickPick`. See [ResponseSpeed](#folder-picker-responsespeed),\n\n- **`[ignoreFocusOut]`**: **boolean** = **true** - whether the UI should stay open even when loosing UI focus. Defaults to **true**,\n\n- **`[showConfigButton]`**: **boolean** = **false** - whether to show a Config button in the top-right corner of the Picker. Defaults to **false**,\n\n- **`[autoNavigate]`**: **boolean** = **false** - whether to auto navigate to a child folder when creating new child folders. Defaults to **false**,\n\n- **`[canPick]`**: **boolean** = **false** - whether to enable picking of current folder in the Picker. Defaults to **true**,\n\n- **`[onCreateFolder]`**: **(folderPath: string) =\u003e void** - called when the New Folder action is triggered, here you should put your logic for folder creation,\n\n- **`[onNavigateTo]`**: **(folderPath: string, ui: vscode.QuickPick) =\u003e void** - called when the user is navigating to an arbitrary absolute path.\n\n- **`[onGoUp]`**: **(folderPath: string, ui: vscode.QuickPick) =\u003e void** - called when the user has clicked on the parent folder entry, that navigates one folder up the directory tree.\n\n- **`[onPickFolder]`**: **(folderPath: string) =\u003e void** - called when the user has picked a folder.\n\n- **`[onError]`**: **(error: Error) =\u003e void** - called when an error has occurred.\n\n- **`[onClose]`**: **() =\u003e void** - called when the user has closed the picker, either by picking a folder, creating a new one, removed focus from the UI - if applicable - `ignoreFocusOut = false`, or pressing `Esc`.\n\n- **`[onConfigButton]`**: **() =\u003e void** - since `v.2.0.0` a Config button is shown at the top right corner of the UI. This callback will be invoked when clicking on it.\n\n- **`[onFetch]`**: **() =\u003e void** - called before the picker fetches directory entries. Most likely this callback will be **removed**.\n\n- **`[onUnspecifiedAction]`**: **(ui: vscode.QuickPick) =\u003e void** - called when there is no action specified. This callback might be triggered in some rare cases - might be removed.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n### Example\n\nthen call it inside your extension's code,\n\n```js\n// some magic code 🔮\n\nshowFolderPicker(directory, {\n  iconFolder: '⚡',\n  iconFolderUp: '🔼',\n  ignoreFocusOut: true,\n})\n\n// even more magic code ✨\n```\n\n\u003cbr\u003e\n\n### Demo\n\n#### Actions\n\n\u003cbr\u003e\n\n##### 🎯 Create\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-create-relative.gif\" alt=\"Command Palette: New Relative Folder\"\u003e\n\t\u003csub\u003eCommand palette command to create a folder in the current directory\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-create-absolute.gif\" alt=\"Command Palette: New Absolute Folder\"\u003e\n    \u003csub\u003eCommand palette command to create a folder with an absolute path\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-recursive-folder.gif\" alt=\"Command Palette: New Recursive Folder\"\u003e\n    \u003csub\u003eCommand palette command to create folders recursively in the current folder\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-invalid-folder.gif\" alt=\"Command Palette: Invalid Folder\"\u003e\n    \u003csub\u003eInvalid folder name supplied\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n##### 🎯 Navigate\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-navigate-relative.gif\" alt=\"Command Palette: Navigate to Relative Folder\"\u003e\n\t\u003csub\u003eNavigation to relative-path folders\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-navigate-absolute.gif\" alt=\"Command Palette: Navigate to Absolute Folder\"\u003e\n\t\u003csub\u003eNavigation to absolute-path folders\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/npm-vscode-folderpicker/main/screenshots/command-palette-pick-folder.gif\" alt=\"Command Palette: Pick Folder\"\u003e\n\t\u003csub\u003ePick a Folder\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorskyflyer%2Fnpm-vscode-folderpicker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorskyflyer%2Fnpm-vscode-folderpicker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorskyflyer%2Fnpm-vscode-folderpicker/lists"}