Ventoy TreeView vs List Mode: Menu Rendering Differences Explained

Ventoy renders boot menus using two distinct behaviors: TreeView creates hierarchical GRUB submenus that mirror directory structures, while List Mode generates a flat scrollable list that displays file sizes and ignores folder hierarchy.

Ventoy supports two primary menu layouts for displaying bootable ISO images: TreeView (hierarchical) and List Mode (flat). These rendering behaviors are controlled by the VTOY_DEFAULT_MENU_MODE configuration option and implemented in the GRUB2 module ventoy_cmd.c. Understanding these architectural differences helps users optimize their USB boot menu for either deep navigation or rapid scanning.

Menu Mode Control and Configuration

The active rendering mode is determined at boot-time by the runtime variable g_default_menu_mode defined in GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_cmd.c (lines 66-71). When this value equals 0, Ventoy renders List Mode; when set to 1, it renders TreeView.

Users configure this via the VTOY_DEFAULT_MENU_MODE key in ventoy.json or through the Ventoy Plugson web interface (plugson_control.html). The Web UI control (lines 228-236) provides a toggle that ultimately updates the internal default_menu_mode variable parsed by Plugson/src/Web/ventoy_http.c.

TreeView Menu Rendering Behavior

TreeView constructs a hierarchical navigation structure using GRUB submenu blocks that mirror the physical directory layout of the ISO files. This implementation resides in the ventoy_dynamic_tree_menu() function within ventoy_cmd.c.

Hierarchical Script Generation

TreeView writes to the global buffer g_tree_script_buf. For each directory node encountered while walking img_iterator_head, the function emits a submenu declaration:

vtoy_ssprintf(g_tree_script_buf, g_tree_script_pos,
    "submenu \"%s\" --class=\"%s\" --id=\"DIR_%s\" _VTIP_%p {\n",
    dir_alias, dir_class, node->dir + offset, tip);

Navigation Entries

Every directory submenu includes a back entry (..) to return to the parent menu:

vtoy_ssprintf(g_tree_script_buf, g_tree_script_pos,
    "menuentry \"%s/..\" --class=\"vtoyret\" VTOY_RET {\n"
    "  echo 'return ...'\n"
    "}\n", node->dir);

When the root node is processed, TreeView inserts a "Return to List View" entry (localized via VTLANG_RET_TO_LISTVIEW) allowing runtime mode switching without rebooting.

Visual Style

The g_tree_view_menu_style flag (lines 70-78) controls directory labeling. When set to 0, directories display with a "DIR" prefix; when set to 1, a compact format is used. File sizes are omitted in TreeView to prioritize navigation clarity over metadata display.

List Mode Menu Rendering Behavior

List Mode generates a flat, scrollable list where every ISO file appears as a top-level menuentry regardless of its directory location. This behavior is implemented in the main image-listing loop within ventoy_cmd.c.

Flat Script Generation

List Mode writes to g_list_script_buf. The rendering iterates over the global linked list g_ventoy_img_list:

for (cur = g_ventoy_img_list; cur; cur = cur->next) {
    vtoy_ssprintf(g_list_script_buf, g_list_script_pos,
        "menuentry \"%s%s\" --class=\"%s\" --id=\"VID_%p\" {\n"
        "  %s_%s \n"
        "}\n",
        cur->unsupport ? "[***********] " : "",
        cur->alias ? cur->alias : cur->name,
        cur->class, cur,
        cur->menu_prefix,
        cur->unsupport ? "unsupport_menuentry" : "common_menuentry");
}

Metadata Display

Unlike TreeView, List Mode always displays file sizes using grub_get_human_size(img->size, …) prepended to the entry name. It also visually marks unsupported ISOs with [***********] prefixes based on the unsupport flag.

Mode Switching Entry

When g_default_menu_mode == 0 (List Mode active), the generated script includes a "Return to Tree View" entry (localized via VTLANG_RET_TO_TREEVIEW) at the top of the menu, allowing users to switch to hierarchical navigation dynamically.

Key Implementation Differences

Feature	TreeView	List Mode
Mode Flag	g_default_menu_mode == 1	g_default_menu_mode == 0
Script Buffer	g_tree_script_buf	g_list_script_buf
Core Function	ventoy_dynamic_tree_menu()	Main image-listing loop
Data Structure	Recursive walk of img_iterator_head	Linear iteration of g_ventoy_img_list
Directory Handling	submenu blocks with DIR IDs	Ignored (flat list)
File Size Display	Hidden	grub_get_human_size() shown
Navigation	Submenu depth with .. back entries	Single scrollable list
Style Control	g_tree_view_menu_style (DIR prefix/compact)	None (fixed format)

Summary

• TreeView uses g_tree_script_buf and the recursive ventoy_dynamic_tree_menu() function to generate nested GRUB submenu structures that mirror directory hierarchies, hiding file sizes and requiring navigation into submenus with back entries (..).

• List Mode uses g_list_script_buf to emit a flat array of menuentry items from g_ventoy_img_list, displaying human-readable file sizes and [***********] markers for unsupported ISOs without any submenu nesting.

• The active mode is determined by g_default_menu_mode (set via VTOY_DEFAULT_MENU_MODE in ventoy.json or Plugson), with both modes providing a runtime switch entry to toggle between views without rebooting.

Frequently Asked Questions

How do I switch between Ventoy TreeView and List Mode?

You can switch modes by setting the VTOY_DEFAULT_MENU_MODE option in your ventoy.json configuration file—use 0 for List Mode or 1 for TreeView. Alternatively, use the Ventoy Plugson web interface (plugson_control.html) to toggle the setting graphically. At boot time, the value is loaded into the g_default_menu_mode variable in GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_cmd.c.

Why are file sizes visible in List Mode but hidden in TreeView?

List Mode explicitly calls grub_get_human_size(img->size, …) when constructing g_list_script_buf to prepend size information to each entry. TreeView prioritizes hierarchical navigation clarity over metadata; the ventoy_dynamic_tree_menu() function in ventoy_cmd.c omits size strings when building g_tree_script_buf to keep submenu labels focused on directory paths.

Can I navigate back to the parent directory in TreeView?

Yes. Every directory submenu generated by ventoy_dynamic_tree_menu() includes a menuentry labeled with .. (or the localized equivalent) that executes VTOY_RET to return to the parent menu. Additionally, the root menu contains a "Return to List View" entry when TreeView is active, allowing you to switch rendering modes dynamically without rebooting.

What is the performance impact of using TreeView versus List Mode?

Both modes iterate over the same underlying g_ventoy_img_list structure during initial scanning, so detection performance is identical. However, TreeView consumes additional memory for g_tree_script_buf to store nested submenu syntax and requires more GRUB script parsing during menu rendering. List Mode uses a simpler g_list_script_buf with flat menuentry declarations, resulting in slightly faster menu initialization when managing thousands of ISO files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}