Folder Selector

FolderSelector is a Dash All-in-One (AIO) component for browsing and selecting a directory. It can operate in two modes: a native OS dialog (tkinter mode) and a browser-based modal with a tree view of the file system (bootstrap mode).

Key features:

• Dual operating modes: Supports tkinter (native OS dialog) and bootstrap (browser modal, requires beta opt-in) modes.

• Automatic mode selection: Automatically selects the best mode based on environment and tkinter availability.

• Flexible configuration: Customizable browse and clear buttons, default path, and maximum path length.

• Readable long-path display: Built-in selected-path display supports line clamping with ellipsis and full-path tooltip on hover.

• Environment variable support: Mode and root path can be configured via environment variables for remote or containerized deployments.

Note

tkinter is Python’s standard library for creating graphical user interfaces (GUIs). It is included in the standard Python library and thus is available by default in most Python installations, but may not be available in some minimal or custom Python installations.

Usage

Warning

The FolderSelector component must be wrapped inside a MantineProvider with a dmc.NotificationContainer present in the application layout for error notifications to work properly. If the notification container is missing or not properly configured, errors fail silently without feedback to the user. See the Add a NotificationContainer section of the Getting Started page for instructions, including how to customize the container id via configure().

Basic usage

Import FolderSelector:

from ansys.solutions.dash_super_components import FolderSelector

Add FolderSelector to the page layout:

def layout():
    return html.Div(
        [
            FolderSelector(
                aio_id="select_folder_basic",
            )
        ]
    )

The following output is expected:

Advanced usage

The following example shows how to use the component in bootstrap mode and customize its button properties and options.

Bootstrap mode is a beta feature and is disabled by default. To enable it, call configure() during app startup (for the package-level beta feature setup, see Enable beta features):

import ansys.solutions.dash_super_components as dsc

dsc.configure(enable_beta_features=True)

To make the FolderSelector use bootstrap mode, import FolderSelectorMode in addition to FolderSelector and set the mode parameter to FolderSelectorMode.BOOTSTRAP when instantiating the component. In addition, pass custom settings in the options dictionary, and customize the appearance of the browse and clear buttons with the browse_button_props and clear_button_props dictionaries:

from ansys.solutions.dash_super_components import FolderSelector
from ansys.solutions.dash_super_components.folder_selector import FolderSelectorMode

def advanced_layout():
    return html.Div(
        [
            FolderSelector(
                aio_id="select_folder_advanced",
                mode=FolderSelectorMode.BOOTSTRAP,
                browse_button_props={
                    "disabled": False,
                    "children": "Select the data source directory",
                },
                clear_button_props={
                    "size": "lg",
                },
                options={
                    "display_field": {"enabled": False},
                    "default_path": "/path/to/default",
                    "browse_from": "/path/to/root",
                    "topmost": True,
                    "max_path_length": 260,
                    "max_tree_depth": 8,
                    "max_children_per_node": 20,
                },
                value="/path/to/preselected/folder",
                style={"margin": "2rem"},
            )
        ]
    )

The following output is expected:

Warning

In bootstrap mode, you must provide a root path for the folder tree by setting either options["browse_from"] or the FOLDER_SELECTOR_BROWSE_FROM environment variable.

Access the selected folder

The selected folder path can be accessed in a callback function using the FolderSelector.ids.selected_folder(aio_id) store ID. The value is a string representing the selected folder path, or None if no folder is selected.

@callback(
    Output("output-div", "children"),
    Input(FolderSelector.ids.selected_folder("select_folder_advanced"), "data"),
)
def display_selected_folder(selected_folder):
    if selected_folder:
        return f"Selected folder: {selected_folder}"
    return "No folder selected"

Warning

The selected folder value is client-side browser state and should be treated as not trusted input (that is, it should be validated before use).

Properties

Constructor parameters

Parameter	Description	Type	Required
mode	The technology to be used to create the folder selector pop-up. Can be FolderSelectorMode.TKINTER or FolderSelectorMode.BOOTSTRAP. If not specified, automatically selects based on tkinter availability and FOLDER_SELECTOR_REMOTE_DEPLOYMENT environment variable when bootstrap beta is enabled via configure(enable_beta_features=True).	FolderSelectorMode	No
aio_id	The unique identifier for the component. If not provided, a UUID is generated.	str	No
browse_button_props	Properties for the browse button. See dmc.Button properties. Default includes a folder icon and “Browse” text.	dict	No
clear_button_props	Properties for the clear button. See dmc.ActionIcon properties. Default includes a delete icon.	dict	No
style	Style properties for the component container.	dict	No
options	Dictionary containing additional configuration options (see below).	dict	No
value	The preselected folder path. Populates the selected folder store upon instantiation.	str	No

Options dictionary

The options parameter accepts a dictionary with the following keys:

Key	Description	Type	Required
default_path	The path to be used as a default value for the selected folder when no folder has been selected yet or the selection has been cleared.	str	No
browse_from	The path to be used as a root for folder selection. Only works with bootstrap mode. In bootstrap mode, this value must be provided either in options or with an environment variable FOLDER_SELECTOR_BROWSE_FROM.	str	No
topmost	If set to True, the dialog window is shown in the foreground (tkinter mode only). Default: True.	bool	No
max_path_length	The maximum length of the path that can be selected. Default: System-dependent maximum path length.	int	No
max_tree_depth	The maximum folder depth included in bootstrap tree generation. Default: 10.	int	No
max_children_per_node	The maximum child folders included for each tree node int in bootstrap mode. Additional folders are omitted from the tree. Default: 100.	No
display_field	Dictionary with enabled (bool) and optional max_display_lines (int) keys. If enabled is True, the selected folder path is displayed below the buttons. The display is truncated with ellipsis after a maximum number of lines specified by max_display_lines and the full path is available via tooltip on hover. Default: {"enabled": True, "max_display_lines": 2}.	dict	No

Component IDs

The component exposes the following IDs for use in callbacks:

• FolderSelector.ids.selected_folder(aio_id): Store containing the selected folder path (str or None)

• FolderSelector.ids.browse_button(aio_id): The browse button component

• FolderSelector.ids.clear_button(aio_id): The clear button component

Operating modes

Tkinter mode

• Uses native OS dialog window for folder selection

• Provides familiar OS-native user experience

• Requires tkinter package to be available

• Selected via mode=FolderSelectorMode.TKINTER

• Respects the topmost option to control window layering

Bootstrap mode

Bootstrap mode is a beta capability for browser-based folder selection in controlled environments when tkinter is not available. It should not be used in production environments.

• Is a beta feature and can only be used when enabled through configure() with enable_beta_features=True (see Enable beta features).

• Uses browser-based modal with tree view of file system

• Works in environments where tkinter is not available (for example, remote deployments)

• Requires browse_from to be defined through options or FOLDER_SELECTOR_BROWSE_FROM environment variable

• Hidden folders and symlink folders are excluded from the tree

• Supports tree-size controls through max_tree_depth and max_children_per_node

• Selected via mode=FolderSelectorMode.BOOTSTRAP

• Automatically activated (when mode is omitted) if bootstrap beta is enabled and FOLDER_SELECTOR_REMOTE_DEPLOYMENT environment variable is set to true, 1, or yes

Operational guidance

• Set browse_from to the narrowest practical root

• Avoid broad roots such as monorepo roots or system-level roots

• Keep max_tree_depth and max_children_per_node conservative for responsiveness

• Prefer tkinter mode for production workflows when native GUI access is available

Environment variables

Variable	Description
FOLDER_SELECTOR_REMOTE_DEPLOYMENT	If set to true, 1, or yes, forces bootstrap mode when bootstrap beta is enabled via configure(enable_beta_features=True). Useful for remote or containerized deployments.
FOLDER_SELECTOR_BROWSE_FROM	Specifies the root path for folder browsing in bootstrap mode. Can be overridden by the browse_from option.

Limitations

• Bootstrap mode is intended for controlled environments with a narrowly scoped browse_from root and trusted usage patterns.

• The tree can omit folders when max_tree_depth or max_children_per_node limits are reached. In that case, the affected nodes include a description message indicating truncation.

• Hidden folders (names beginning with .) and symlink folders are intentionally excluded from the bootstrap tree.

• If tkinter is unavailable and bootstrap beta is not enabled, folder browsing is blocked and the component shows a notification explaining how to enable bootstrap mode. See Enable beta features.

Full example

For a complete working example, check out the showcase example.

The example demonstrates:

• A basic folder selector using default settings, with the selected path displayed via a callback

• Switching between bootstrap and tkinter modes, toggling the built-in path display field, toggling a default path, and setting max_display_lines via the options dictionary

• Custom styling of the component container, browse button, and clear button

• Two folder selectors demonstrating persistence strategies: no persistence (resets on recreation) and backend persistence (restored from the server per project)

For a minimal self-contained runnable example, see the Folder Selector page in the Examples gallery.

Notes

• Consider preserving the selected folder value by passing it to the value parameter, so it gets preserved when recreating the component with different settings etc.

• The browse_from option is only effective in bootstrap mode and has no effect in tkinter mode

• Path validation is automatically performed based on the max_path_length setting

Source code

For the full API reference of FolderSelector, see FolderSelector.

Check out the component source code to discover the underlying logic. Contributions are welcomed. You can extend the component functionalities by raising a pull request in the super-components-for-dash repository.