Home

An introduction to Fancytree.

Main Features

Lazy loading and efficient and performant handling of large data sets
Keyboard navigation
WAI-ARIA compliant
Table view support (aka tree grid)
(Hierarchical) selection and checkboxes
Drag and drop (html5 or jQuery UI based)
Inline editing
Searching and filtering
Persistence of expansion, selection, and active state
Themable (comes with WinXP, Win7, Win8, OS X Lion, and Glyph samples)
The tree behaves like a single form control, i.e. it is 'tabbable' (example)
Rich object oriented API
Extensible modular design
and more... see the list of available extensions

Try the Demos

Have a look at the Example Browser to play with live demos. Click the View source link at the bottom of every page to see what's going on.

Getting Started

Requirements:

jQuery 1.8.6+ (3.x recommended)
The distribution contains jquery.fancytree-all-deps.min.js, which already includes the minimal required subset of jQuery UI dependencies. So the only external dependency is jQuery.
Optionally, if your project is already including jQuery UI 1.9+ anyway, use jquery.fancytree-all.min.js instead.
If a custom download is used, at least the following components should be selected:
'UI Core',
'Effects': 'Effects Core', 'Blind Effect'
The ext-dnd extension also requires 'Interactions': 'Draggable', 'Droppable', however the ext-dnd5 extension does not have this dependencies.

There are several ways to get the latest Fancytree release:

If you use bower, a simple $ bower install fancytree will download the latest stable release.
If you use npm Registry, a simple $ npm install jquery.fancytree will download the latest stable release.
Include a CDN link to jsdelivr, cdnjs, or UNPKG on your page.
With a little configuration, Fancytree can also be included using AMD / require.js.
It is recommended to use jquery.fancytree-all-deps.min.js, so the distinct jQuery UI dependencies don't need to be listed as external requirement.
Open a release from the release list and download the complete source tree with documentation, tests, etc. by clicking Source code (zip). You will find the production library and CSS files in the dist/ folder.
You can also click Download ZIP at the project page to get the latest development snapshot. Note that the dist/ folder still contains the latest released version. You have to run npm install and grunt build to create current minified files in the build/ folder (see here for details).

Currently we deliver

fancytree/
├─ demo/                                 Example browser
├─ src/                                  Current development code ('nightly build')
├─ test/                                 Unit tests and triage
└─ dist/                                 Latest released version:
   ├─ jquery.fancytree.js                  Core library (no extensions)
   ├─ jquery.fancytree.min.js              Same as above, minified
   ├─ jquery.fancytree-all.js              Library with most extensions (uncompressed)
   ├─ jquery.fancytree-all.min.js          Library with most extensions, minified
   │                                         and with AMD support. This is what you
   │                                         would use for production IF you want
   │                                         to include jQuery UI separately.
   │                                         (maybe removing unwanted extensions)
   ├─ jquery.fancytree-all-deps.min.js     This library additionally includes the
   │                                         required parts of jQuery UI.
   ├─ skin-common.less                     Shared CSS, used by stock themes
   ├─ src/                                 This folder contains all single extensions
   ├─ skin-NAME/                           CSS styles for the stock theme NAME
   └─ skin-custom-1/                       Starting point for a custom theme

See HowtoContribute for details on how to install Fancytree for debugging and contributing.

Understand the Core Concepts

This is not required for standard use cases, but you might want to come back to read about the Main Concepts later on.

Embed Fancytree on Your Web Page

The most simple way to create a tree is like that:

<head>
  [...]
  <!-- Include jQuery -->
  <script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
  <!-- Include Fancytree skin and library -->
  <link href="fancytree/skin-win8/ui.fancytree.min.css" rel="stylesheet">
  <script src="fancytree/jquery.fancytree-all-deps.min.js"></script>
  <!-- Initialize the tree when page is loaded -->
  <script type="text/javascript">
    $(function(){
      // Create the tree inside the <div id="tree"> element.
      $("#tree").fancytree({ ... });
    });
  </script>
</head>
<body>
  [...]
  <!-- Define where the tree should appear -->
  <div id="tree">...</div>
  [...]
</body>
</html>

Define the Tree Data

There are several ways to define the actual node structure:

Use the source option to pass a data structure, i.e. an array of nested objects:

  source: [
    {title: "Node 1", key: "1"},
    {title: "Folder 2", key: "2", folder: true, children: [
      {title: "Node 2.1", key: "3"},
      {title: "Node 2.2", key: "4"}
    ]}
  ],
  ...

See also the complete list of data properties.

Use the source option to load the data via ajax.

  source: {
    url: "/getTreeData",
    cache: false
  },
  ...

The ajax service is expected to return valid JSON data:

[{"title": "Node 1", "key": "1"},
 {"title": "Folder 2", "key": "2", "folder": true, "children": [
    {"title": "Node 2.1", "key": "3"},
    {"title": "Node 2.2", "key": "4"}
  ]}
]

Define a <ul>/<li> markup structure inside the tree's <div> tag.

$("#tree").fancytree();

<div id="tree">
  <ul id="treeData" style="display: none;">
    <li id="1">Node 1
    <li id="2" class="folder">Folder 2
      <ul>
        <li id="3">Node 2.1
        <li id="4">Node 2.2
      </ul>
  </ul>
</div>
  ...

For more information see also TutorialLoadData and the online demo.

Lazy Loading

Fancytree supports loading nodes on demand, i.e. only load data when a node is expanded for the first time.

In order to enable this, we can mark nodes as lazy.

  $("#tree").fancytree({
    // Initial node data that sets 'lazy' flag on some leaf nodes
    source: [
      {title: "Child 1", key: "1", lazy: true},
      {title: "Folder 2", key: "2", folder: true, lazy: true}
    ],
    lazyLoad: function(event, data) {
      var node = data.node;
      // Issue an ajax request to load child nodes
      data.result = {
        url: "/getBranchData",
        data: {key: node.key}
      }
    }
  });

For more information see TutorialLoadData.

Configure Options

Additional options are passed to Fancytree during initialization:

$("#tree").fancytree({
  source: {
    url: "ajax-tree-plain.json"
  },
  checkbox: true,
  [...]
});

Options can also be set after initialization using this syntax:

$("#tree").fancytree("option", "checkbox", true);

For more information see also the complete list of available options and the Option Configurator.

Dynamic Options

Some node options can be defined in a flexible way using a dynamic pattern.

Consider for example the checkbox option, which may be true, false, or "radio". If ommitted, it will default to false. Globally enabling checkboxes for all nodes can be configured like so:

  $("#tree").fancytree({
    checkbox: true,
    source: {url: "/mySource"},
    ...

This global setting may be overridden per node by the concrete source data, if a property of the same name is present:

[{"title": "Node 1"},
 {"title": "Node 2", "checkbox": false},
 {"title": "Node 3", "checkbox": "radio"}
 ]

If the global setting is a callback, it will be called for every node, thus allowing to dynamically define option values:

  $("#tree").fancytree({
    checkbox: function(event, data) {
      return data.node.isFolder() ? false : true;
    },
    tooltip: function(event, data) {
      return data.node.title + " (" + data.node.key + ")";
    },
    ...

Currently the following options are evaluated as dynamic options: checkbox, icon, tooltip, unselectable, unselectableIgnore, unselectableStatus.

Event Handling

Functionality can be added (and modified) by defining event handlers (i.e. callback functions).

Every event handler is passed a data argument, that contains information about the event target.

  $("#tree").fancytree({
    ...
    activate: function(event, data){
      // A node was activated: display its title:
      var node = data.node;
      $("#echoActive").text(node.title)
    },
    beforeSelect: function(event, data){
      // A node is about to be selected: prevent this, for folder-nodes:
      if( data.node.isFolder() ){
        return false;
      }
    }
  });

An alternative way to define event handlers is to bind them later to an initialized tree. Note that the event name must be converted to lower case and prefixed with 'fancytree':

  $("#tree").on("fancytreebeforeselect", function(event, data){
    if( data.node.isFolder() ){
      return false;
    }
  });

For more information see also TutorialEvents, the online demo, the complete list of available events, and a description of the 'data' object.

API Access

Fancytree exposes an extensive, object oriented interface to query and manipulate the data model:

  var tree = $("#tree").fancytree("getTree"),
      activeNode = tree.getActiveNode();

  // Sort children of active node:
  activeNode.sortChildren();
  // Expand all tree nodes
  tree.visit(function(node){
    node.setExpanded(true);
  });
  // Append a new child node
  activeNode.addChildren({
    title: "Document using a custom icon",
    icon: "customdoc1.gif"
  });

For more information see TutorialApi.

Selection and Checkboxes

Fancytree supports three modes:

selectMode: 1: single selection
Only one node is selected at any time.
selectMode: 2: multiple selection (default)
Every node may be selected independently.
selectMode: 3: hierarchical selection
(De)selecting a node will propagate to all descendants. Mixed states will be displayed as partially selected using a tri-state checkbox.

While the selected state of a node is indepependant of a checkbox icon, we would typically enable checkboxes for the tree using the checkbox: true option. (The special value "radio" turns checkoxes into radio buttons.)

Propagation in select mode 3 can be controlled using unselectable, unselectableStatus, and unselectableIgnore options.
The node option radiogroup enables single-select for its child nodes.

See the online demo and details.

Theming

Some skins are part of the distribution (Win-XP, Windows 7, Windows 8, OS X Lion, ...). Use the Skin combobox on the online demo, to try them out.

Some more info here.

Extensions

Fancytree is extensible using extensions. The standard distribution already contains some extra functionality in this way, such as table-support, inline editing, filtering, etc.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly