Usage Guide

This guide covers the core features of jOrgChart in more detail.

Initializing the Chart

The plugin is initialized on a jQuery selector that points to your data source, which should be a <ul> or <li> element.

The most basic initialization is:

$("#your-list-id").jOrgChart();

This will generate the chart and append it to the <body> element of your page.

A more common approach is to specify a target container for the chart:

$("#your-list-id").jOrgChart({
  chartElement: '#your-chart-container'
});

HTML Data Structure

jOrgChart renders a chart based on the nesting of <li> elements inside a <ul>.

The content of each <li> becomes the content of a node in the chart.
A <ul> nested inside an <li> creates child nodes for that <li>.

Node Content

You can place any HTML markup inside your <li> elements, except for other <ul> or <li> elements. The plugin will copy this markup into the corresponding <div> node in the chart.

Example:

<ul id="org-data" style="display:none">
  <li>
    <h4>Main Branch</h4>
    <p>This is the root node.</p>
    <a href="#">More info</a>
    <ul>
      <li>
        <img src="images/icon.png" alt="icon"/>
        <p>Child Node 1</p>
      </li>
      <li>Child Node 2</li>
    </ul>
  </li>
</ul>

Interacting with the Chart

Expanding and Collapsing Nodes

If a node has children, you can click on it to toggle the visibility of its entire branch. The cursor will change to indicate that a node is interactive.

Collapsing Branches by Default

For large charts, you may want some branches to be collapsed when the page first loads. To achieve this, add the class collapsed to any <li> element. That node will be visible, but all of its descendants will be hidden until it is clicked.

Example:

<ul id="org-data" style="display:none">
  <li>
    Food
    <ul>
      <li>Beer</li>
      <li class="collapsed">Vegetables <!-- This branch will be collapsed by default -->
        <ul>
          <li>Carrot</li>
          <li>Pea</li>
        </ul>
      </li>
      <li>Chocolate</li>
    </ul>
  </li>
</ul>

Drag and Drop

To enable drag-and-drop functionality, you must first include the jQuery UI library (see Installation) and then set the dragAndDrop option to true during initialization.

$("#org-data").jOrgChart({
  chartElement: '#chart-container',
  dragAndDrop: true
});

When drag-and-drop is enabled, you can click and drag any node and drop it onto another node. This action moves the dragged node (and its entire sub-tree) to become a child of the target node.

Importantly, this action updates both the visual chart and the original, hidden <ul> data source in the DOM. This means if you are saving the structure to a server, you can always read the latest state from the DOM.