jqTreeSelect

Installation#

Load jQuery (3.x+ recommended). The plugin is completely standalone and includes built-in inline SVGs, so Bootstrap 5 and FontAwesome are optional. Include the jqTreeSelect CSS and JavaScript files.

CSS Stylesheet

<!-- jqTreeSelect Custom Styles -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/umairwebdeveloper/jqTreeSelect/dist/jq-tree-select.min.css">

Javascript Plugin

jqTreeSelect includes a UMD (Universal Module Definition) wrapper, allowing it to load cleanly in standard browsers, AMD modules, and Node/CommonJS module systems.

Method A: Standard Browser Inclusion

<!-- JQuery 3.x -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

<!-- jqTreeSelect Custom Script -->
<script src="https://cdn.jsdelivr.net/gh/umairwebdeveloper/jqTreeSelect/dist/jq-tree-select.min.js"></script>

<!-- Optional: Bootstrap 5 for better UI -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"></script>

Method B: Webpack / Browserify / CommonJS

// Import jQuery and the plugin
const $ = require('jquery');
require('./jq-tree-select.js')($); // pass jQuery context

Method C: RequireJS (AMD)

require(['jquery', 'jq-tree-select'], function($) {
    // Plugin initialized
    $('#mySelect').jqTreeSelect();
});

Quick Start & Auto-Init#

jqTreeSelect can be initialized in two different ways depending on your application needs:

Method 1: Codeless Auto-Init (Data-API)

Simply add the attribute data-toggle="jq-tree-select" to your native multi-select element. The plugin will automatically instantiate it when the document loads, reading configuration options directly from any data-* attributes defined on the element.

<!-- Auto-initialized tree with search enabled, width 320px -->
<select class="form-control" multiple 
        data-toggle="jq-tree-select" 
        data-search-enabled="true"
        data-layout-width="320px">
    <option value="1">Option A</option>
    <option value="2">Option B</option>
</select>

Method 2: Programmatic JQuery Call

Instantiate options programmatically by calling .jqTreeSelect() on your jQuery selectors.

<select id="manualSelect" class="form-control" multiple>
    <option value="1">Option 1</option>
    <option value="2" selected>Option 2</option>
</select>

$(document).ready(function() {
    $('#manualSelect').jqTreeSelect({
        search: {
            enabled: true
        },
        actions: {
            showSelectAll: true,
            showClearAll: true
        }
    });
});

Interactive Configurator#

Toggle and customize different options in real-time, view the rendered widget live, and copy the instantly compiled JQuery or HTML data attributes markup.

Configuration Options Reference#

The global options schema allows full customization. Grouped into structured nested namespaces.

1. Layout Settings (layout)

2. Header Quick Actions (actions)

3. Tree & Nesting Settings (grouping)

4. Search Settings (search)

HTML5 Data Attributes Configuration#

Set options directly in your markup to configure individual instances. These automatically override the global defaults.

Dynamic Data Source (Array Loading)#

Load and build options dynamically by passing a javascript array of objects directly in the data parameter.

1. Flat List Format

$('#mySelect').jqTreeSelect({
    data: [
        { value: "1", text: "Alpha Node" },
        { value: "2", text: "Beta Node", selected: true },
        { value: "3", text: "Disabled Node", disabled: true }
    ]
});

2. Single-level Grouping

$('#mySelect').jqTreeSelect({
    grouping: { nested: true },
    data: [
        {
            groupName: "Fruits",
            groupId: "g_fruits",
            options: [
                { value: "f1", text: "Apple" },
                { value: "f2", text: "Banana", selected: true }
            ]
        },
        {
            groupName: "Vegetables",
            groupId: "g_vegetables",
            options: [
                { value: "v1", text: "Spinach" }
            ]
        }
    ]
});

3. Unlimited Depth Tree (Path Format)

Provide a groupPath (using slashes /) to nested folders. The plugin programmatically compiles nodes and subnodes to arbitrary depth.

$('#mySelect').jqTreeSelect({
    grouping: { 
        nested: true,
        collapsible: true
    },
    data: [
        { 
            value: "w1", 
            text: "Create Users", 
            groupPath: "Admin/Permissions/User Operations",
            groupCollapsed: false 
        },
        { 
            value: "w2", 
            text: "Edit Profiles", 
            groupPath: "Admin/Permissions/User Operations" 
        },
        { 
            value: "r1", 
            text: "Read Logs", 
            groupPath: "Admin/Logs" 
        }
    ]
});

Events & Callbacks Reference#

Expose and trigger interaction lifecycle hooks either via setting properties or native jQuery DOM event listeners.

Lifecycle Event Mappings

Usage Example

// Method A: JavaScript callbacks parameter
$('#mySelect').jqTreeSelect({
    callbacks: {
        onChange: function(detail) {
            console.log("Selected values array: ", detail.selectedValues);
        }
    }
});

// Method B: Standard JQuery event listeners
$('#mySelect').on('jqtree:change', function(event, detail) {
    console.log("Change registered on DOM: ", detail.selectedValues);
});

Public API Methods#

Trigger actions programmatically by passing the method name string as parameters.

Example Trigger Code

// Clear all selections
$('#mySelect').jqTreeSelect('clear');

// Fetch current values
let currentList = $('#mySelect').jqTreeSelect('val');
console.log(currentList);

Contact & Support#

Got a problem, found a bug, or need help integrating the plugin? I'm always happy to help out.