📃 Table of Contents

• Features
• Motivation
• Usage
• API
• Examples
• Demo
• Changelog
• Support
• License
• Related
• Author

🤖 Features

• ✨ Fast Folder Selection
• 🎨 Icons With Clear Visuals
• ⚡ Instant Navigation
• ✅ Path Validation
• 🛠️ Configurable Buttons
• 🎯 Custom Handlers & Events
• 📂 Create & Navigate Folders
• 🔔 Error & Action Callbacks

🎯 Motivation

This module powers my New Folder VS Code extension.
It is under active development - expect breaking changes.

The goal

Provide a simple UI/UX for creating new folders when opening a new or blank VS Code instance, since that behavior is not built‑in.

Why not use showSaveDialog()?

• Works only if files.simpleDialog.enable is set to true (a global preference that changes the UX for all file/folder dialogs).
• Limited to creating a single‑level child folder - no nested/recursive folder creation.

What happened upstream?

• I filed a feature request #127201 with @microsoft/vscode.
• The request was closed as by design.

The result

I built my own UI and logic to overcome these limitations.
This project is the outcome of that effort.

🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

pnpm add @igorskyflyer/vscode-folderpicker

yarn add @igorskyflyer/vscode-folderpicker

npm i @igorskyflyer/vscode-folderpicker

🤹🏼 API

ResponseSpeed

enum ResponseSpeed

Used 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 is provided by Zep().

Available values are: Instant, Fast, Normal (default), Lazy.

🛑 CAUTION

Throttling

Setting this property to ResponseSpeed.Instant disables all throttling/debouncing!

showFolderPicker()

showFolderPicker(directory: string, options?: Partial<IFolderPickerOptions>): void

Parameters

directory: string - Initial directory to display in the picker.

options: Partial<IFolderPickerOptions> - Optional configuration to customize behavior and UI.

Options

IFolderPickerOptions

UI/UX

• [dialogTitle]: string = 'Pick a Folder' - Title text displayed at the top of the dialog. Defaults to 'Pick a Folder'.

• [showIcons]: boolean = true - Whether to show icons next to folder items. Defaults to true.

Be aware that the term icon is used here descriptively.

This property expects either:

• a single emoji (e.g. 📂), or
• a VS Code ThemeIcon (string shorthand like '$(gear)' or an object instance new ThemeIcon('gear')).

To see the list of available ThemeIcons, look at the official Visual Studio Code documentation.
See the [Icons] section below.

• [showConfigButton]: boolean = false - Whether to display a configuration (⚙️) button in the UI. Defaults to false.

• [autoNavigate]: boolean = false - Whether to auto navigate to a child folder when creating new child folders. Defaults to false.

• [responseSpeed]: ResponseSpeed | number = ResponseSpeed.Normal - Controls how quickly the picker responds to user input. Can be a predefined ResponseSpeed or a custom debounce interval in ms. See ResponseSpeed. Defaults to ResponseSpeed.Normal.

• [ignoreFocusOut]: boolean = false - Whether the picker remains open when focus is lost. Defaults to false.

• [canPick]: boolean = true - Whether to enable picking of current folder in the Picker. Defaults to true.

Icons

• [iconFolder]: LabelIcon (string | ThemeIcon) = '' - Icon used for folder entries.

• [iconFolderUp]: LabelIcon (string | ThemeIcon) = '' - Icon used for the go up (parent folder) action.

• [iconCreate]: LabelIcon (string | ThemeIcon) = '' - Icon used for the create new folder action.

• [iconNavigate]: LabelIcon (string | ThemeIcon) = '' - Icon used for navigation actions.

• [iconPick]: LabelIcon (string | ThemeIcon) = '' - Icon used for the pick action.

• [iconClear]: LabelIcon (string | ThemeIcon) = '' - Icon used for the clear action.

Behavior

• [onCreateFolder]: FolderActionCallback - Fired when a new folder is created.

• [onPickFolder]: FolderActionCallback - Fired when a folder is picked/selected.

• [onNavigateTo]: FolderActionCallback - Fired when navigating into a folder.

• [onGoUp]: FolderActionCallback - Fired when navigating up to the parent folder.

• [onFetch]: FetchCallback - Fired before fetching folder contents.

• [onFetched]: FetchCallback - Fired after folder contents have been fetched.

• [onClose]: UICallback - Fired when the picker is closed.

• [onConfigButton]: UICallback - Fired when the configuration button is pressed. Requires showConfigButton to be set to true.

• [onError]: ErrorCallback - Fired when an error occurs (always receives an Error).

• [onUnknownAction]: UnknownActionCallback - Fired for actions not covered by other handlers. Provides full access to the underlying QuickPick.

🗒️ Examples

// some magic code 🔮

import { showFolderPicker } from '@igorskyflyer/vscode-folderpicker'
import { ThemeIcon } from 'vscode'

showFolderPicker('/Users/igor/projects', {
  dialogTitle: 'Select a folder',
  onPickFolder: folderPath => {
    console.log('Picked folder:', folderPath)
  }
})

// even more magic code ✨

👁️ Demo

📝 Changelog

📑 Read about the latest changes in the CHANGELOG.

🪪 License

Licensed under the MIT license.

💖 Support

🧬 Related

@igorskyflyer/normalized-string

💊 NormalizedString provides you with a String type with consistent line-endings, guaranteed. 📮

@igorskyflyer/valid-path

🧰 Determines whether a given value can be a valid file/directory name. 🏜

@igorskyflyer/comment-it

📜 Formats the provided string as a comment, either a single or a multi line comment for the given programming language. 💻

@igorskyflyer/jmap

🕶️ Reads a JSON file into a Map. 🌻

@igorskyflyer/is-rootdir

🔼 Checks whether the given path is the root of a drive or filesystem. ⛔

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).