Documentation › How to group boxes using custom field for Org Chart

Group employees boxes using custom field for Org Chart

Employee boxes grouped by Department field in Compact layout

You can group employee boxes dynamically by field value. To set this up, you’ll just need to either configure your view or apply some custom JavaScript and define a few specific properties.

Before starting

First, make sure you’re using the correct layout for your view type.

For Org Chart views, you must select the Compact layout:

  1. Open the Views panel and select the specific view you’d like to edit.

  2. Under the layout options, choose Compact as your layout style.

Compact layout selected in Org Chart Views panel

Alternatively, if you are using an Employee Directory view, the grouping option is available with both layout types:

  • Cards

Employee cards grouped by department in Employee Directory view

  • List

Grouped employee list by department in Employee Directory view

Note

Employee Directory views are not supported when using User Profiles as data source.

View configuration

The most intuitive way to organize your chart is through the Views panel.

  1. Navigate to the Views sidebar.

  2. Use the Group by dropdown to select the specific data field (e.g.,Department) you wish to use. If no field is selected, the chart will display your employees based on the hierarchy defined in your data source.

Group by dropdown for selecting a field in Org Chart view settings

Use custom code

Alternately, you can also implement your own grouping logic in Org Chart views using custom code.

If you’re considering using custom code, we recommend taking a quick look at the following documentation to get the most out of this feature:

To set up custom grouping, you’ll need to use a combination of the following methods and properties. You should review the details for each to ensure everything is configured correctly.

Methods

Properties

To implement the grouping, you will use the displayNodesGroupingForLevel method. To see this in action, let’s walk through an example on how to group the first level of the chart by the “Department” field:

api.displayNodesGroupingForLevel(
  1, // Node level
  "Department", // Grouping field name
  false, // Show labels
  "d8e7639f-824d-4911-a12e-eb3d9c4db79c" // View ID
);

You can find the specific View ID in the Views panel by locating your desired option and copying its unique value.

View ID copied from Org Chart Views panel

Including the viewId parameter is optional; if you omit it or set it to null, the configuration will automatically apply to the first view in your list.

Once you have your parameters ready, navigate to the Custom Code panel and open the JavaScript tab to paste your code.

Custom JavaScript code for grouping Org Chart boxes by Department field

Note

Editing JavaScript is available only for Tenant Administrators (Global Administrators). Also, the Tenant Administrator can disable the Custom JavaScript feature globally.

If you aren’t sure of the exact field name to use for grouping, you can find it under the Field names menu. In this example, we are using “Department”:

Field names menu showing Department field for Org Chart grouping

After you have updated the method with your specific values, simply save your changes in the editor.

To make the grouping labels visible later on, just switch the third parameter to true:

api.displayNodesGroupingForLevel(
  1, // Node level
  "Department", // Grouping field name
  true, // Show labels
  "d8e7639f-824d-4911-a12e-eb3d9c4db79c" // View ID
);

For more advanced styling, feel free to review our examples on how to customize label boxes.

Sorting

By default, grouping labels are sorted alphabetically. If you want to use a different order in your Org Chart views, you can define a custom sorting function.

For example, you can move all departments whose names start with External to the end of the list:

api.customFunctions.sortGroups = function(groupLabelA, groupLabelB) {
  const isExternal = (label) => label?.startsWith("External"); // Replace with your own logic

  if (isExternal(groupLabelA)) return 1;
  if (isExternal(groupLabelB)) return -1;

  return (groupLabelA ?? "").localeCompare(groupLabelB ?? "");
}

Considerations

Keep these rules in mind when configuring grouping with custom code:

  • setNodeGroupingById has the highest priority.

It can override grouping settings defined by displayNodesGroupingForLevel or displayNodesGroupingForLevels for a specific node.

  • displayNodesGroupingLabels only shows or hides grouping labels. It does not change how employee boxes are grouped.