TutorialTheming

About customizing Fancytree appearance.

See also the online sample.

Customize Icons

Note: the previous options icons (with trailing 's'), iconClass, and iconclass have been deprecated since v2.14. See migration info at the end of this document.

There are multiple ways to customize the standard icons or display icons depending on node types or attributes:

1. In order to change the overall look and feel, a new theme could be created as described below.

2. Hide icons altogether.
   The tree option icon: false will hide all icons (except for nodes that have explicitly set the node option icon: true).

3. When ext-glyph is used, icons are defined by the preset and map options. However the following methods may still be used to override these defaults.

4. Define icons based on initialization data or callbacks.
   The node initialization data icon: "icon_path_or_class" is evaluated by the renderer. In addition, the global tree option icon can be used to define defaults or implement a callback that returns custom configuration per node. See details below.

5. Define icons at runtime using the API.
   The icon option may also be set at runtime. In this case the node must be rendered again to reflect the change:

   node.icon = "icon_path_or_class";
   node.renderTitle();

6. Override standard CSS with custom rules.
   For example override the theme's default folder icons with this CSS:

   span.fancytree-node.fancytree-folder > span.fancytree-icon {
     background-position: 0 0;
     background-image: url("customFolder.gif");
   }
   span.fancytree-node.fancytree-folder.fancytree-expanded > span.fancytree-icon {
       background-image: url("customFolderOpen.gif");
   }

7. Customize node style depending on extraClasses
   This is yet another option, as explained below.

Customize Icons Using options.icon and node.icon

The icon option is implemented as dynamic option, so if opts.icon is a callback function, the return value is evaluated:

$("#tree").fancytree({
  icon: function(event, data) {
    if( data.node.isFolder() ) {
      return "my-folder-icon-class";
    }
    // Otherwise no value is returned, so continue with default processing
  },
  ...
});

Icons can also be defined per node, for example

$("#tree").fancytree({
  source: [
    {title: "foo", icon: "my-foo-icon-class"},
    ...
  ],
  ...
});

Icons can be defined as

• false: Hide icon
• true: Show default icon
• string containing a '.' or '/':
  Assume an image URL and generate an <img> tag instead of standard <span> markup.
• string otherwise:
  Assume a class name and generate a <span class="fancytree-custom-icon my-foo-class"> tag.
• object:
  Can be used to define ligature icons (like Material). Especially useful with ext-glyph, for example:
  {text: "help_outline", addClass: "material-icons"}

See also the description of Dynamic Options.

See also node types for a way to define icons per node-type instead of per distinct node.

Customize Node Style

Customize Node Style Depending on node.extraClasses

The node.extraClasses option adds classes to the node markup:

<span class="fancytree-node custom1">
  <span class="fancytree-expander"></span>
  <span class="fancytree-icon"></span>
  <span class="fancytree-title">Node 1</span>
</span>

Note that in contrast to the icon option, the custom class is added to the surrounding node-span. This allows to modify the appearance of all embedded <span> tags:

span.fancytree-node.custom1 > span.fancytree-icon {
  background-position: 0 0;
  background-image: url("customDoc2.gif");
}
span.fancytree-node.custom1 > span.fancytree-title {
  color: maroon;
  font-family: "Audiowide";
}

This can also be done using the API.

Note: While it is possible to add CSS classes to elements directly, this is not recommended, because those classes would be removed when the node is rendered the next time.
Instead, classes should be listed in the node.extraClasses property to make them sticky. A convenient way to do achieve this, is using special API methods:

node.addClass("custom1");
node.removeClass("custom2");
node.toggleClass("warning", !!node.data.isCritical);

Define a New Theme

Create a custom theme with custom css rules and sprites (icons.gif) in order to change the overall look and feel.

It is recommended to use the Less CSS pre-processor, create a new theme folder, and add custom ui.fancytree.less file that includes skin-common.less

(Of course it is also posible to edit the CSS files directly, but that may be harder to maintain if the standard themses are updated.)

See here for an example: /src/skin-custom-1

Recipes

[Howto] Change the Checkbox Icons

Replace standard checkbox icons with custom variants (e.g. pin symbols):

#tree.pinCheckboxes span.fancytree-checkbox {
   background-position: 0 0;
   background-image: url("../app/img/pin_16x16_up.png");
}
#tree.pinCheckboxes span.fancytree-selected span.fancytree-checkbox {
   background-image: url("../app/img/pin_16x16_down.png");
}
#tree.pinCheckboxes span.fancytree-checkbox:hover {
   background-image: url("../app/img/pin_16x16_up_hover.png");
}
#tree.pinCheckboxes span.fancytree-selected span.fancytree-checkbox:hover {
   background-image: url("../app/img/pin_16x16_down_hover.png");
}

Only apply those CSS rules when a special class is present on the container:

<body>
    ...
    <div id="tree" class="pinCheckboxes">
    </div>
</body>

Updating from Fancytree ≤ 2.13

Release 2.14 introduced the following changes:

• The previous options icons (with trailing 's'), iconClass, and iconclass have been deprecated
• [Added] options.icon option/callback.
  Valid values are true, false, a string containing a class name or image url, or a callback returning that.
• [Changed] node.icon option. Valid values are true, false, or a string containing a class name or image url.
  This option existed before, but was stored in the node.data.icon namespace, and did not accept class names.
• [Deprecated] options.iconClass callback: use options.icon instead
• [Deprecated] options.icons: use options.icon instead
• [Deprecated] node.data.iconclass option: use node.icon instead
• [Deprecated] node.data.icon option: use node.icon instead