CategoricalChart

Save PDF

Last Updated: May 5, 2026
8 minute read

MarkLogic Server
Documentation

The CategoricalChart widget displays charts based on categorical data. Charts are configured by passing settings from the KendoReact Chart component. See API, config API, and *ChartProps API for additional information.

The CategoricalChart widget supports:

Area charts
Bar charts
Column charts
Donut charts
Line charts
Radar line charts
Pie charts

Area chart

Bar chart

A bar chart.

Column chart

Donut chart

Line chart

Radar line chart

Pie chart

Display formatted data in a chart

The CategoricalChart widget can display formatted data. Formatted data should be passed as an array of objects with value and category properties as shown in this example.

import './App.css';
import { CategoricalChart } from "ml-fasttrack";
  
function App() {
  
  const dataFormatted = [
    {
      category: new Date(2024, 0, 1),
      value: 1
    },
    {
      category: new Date(2024, 0, 2),
      value: 2
    }
  ]
 
  return (
    <div className="App">
      <div style={{width: '480px'}}>
        <CategoricalChart
          data={dataFormatted}
          chartType="line"
        />
      </div>
    </div>
  );
}
  
export default App;

Code explanation

In this example:

An array of objects is passed as the data prop.
The chartType prop specifies the type of chart.

Example rendering

The code in Display formatted data in a chart renders this line chart:

The code in this section renders this chart.

Display transformed data in a chart

Data can be transformed using a transformation function defined with the transformData prop. In this example, the code transforms an array of arrays into an array of objects. An array of objects is required by the widget. The chartType prop specifies the type of chart:


import './App.css';
import { CategoricalChart } from "ml-fasttrack";
  
function App() {
 
  const dataRaw = [
    [ "active", 1],
    [ "inactive", 2]
  ]
 
  const transformData = (dataArray) => {
    return dataArray.map(item => ({
        category: item[0],
        value: item[1]
    }))
  }
 
  return (
    <div className="App">
      <div style={{width: '480px'}}>
        <CategoricalChart
          data={dataRaw}
          chartType="donut"
          transformData={transformData}
        />
      </div>
    </div>
  );
}
  
export default App;

Code explanation

In this example:

The code transforms an array of arrays into an array of objects.
An array of objects is required by the widget.
The chartType prop specifies the type of chart.

Example rendering

Display search result data in a chart

The CategoricalChart widget can display values from search result documents.

Example search results

This example assumes that an application returns these search results:

Note:

This example also applies to Display facet data in a chart.

  {
      "total": 3,
      "start": 1,
      "page-length": 10,
      "selected": "include",
      "results": [
          {
              "index": 1,
              "uri": "/person/1001.json",
              "extracted": {
                  "kind": "array",
                  "content": [
                      {
                          "envelope": {
                              "entityType": "person",
                              "id": 1001,
                              "firstName": "Nerta",
                              "lastName": "Hallwood",
                              "dob": "1985-03-04",
                              "salary": 104000,
                          }
                      }
                  ]
              }
          },
          {
              "index": 2,
              "uri": "/person/1002.json",
              "extracted": {
                  "kind": "array",
                  "content": [
                      {
                          "envelope": {
                              "entityType": "person",
                              "id": 1002,
                              "firstName": "Shaylynn",
                              "lastName": "Guard",
                              "dob": "1964-09-30",
                              "salary": 55000
                          }
                      }
                  ]
              }
          },
          {
              "index": 3,
              "uri": "/person/1003.json",
              "extracted": {
                  "kind": "array",
                  "content": [
                      {
                          "envelope": {
                              "entityType": "person",
                              "id": 1003,
                              "firstName": "Pris",
                              "lastName": "Sizland",
                              "dob": "1988-12-15",
                              "salary": 87000
                          }
                      }
                  ]
              }
          }
      ],
      "facets": {
          "status": {
              "type": "xs:string",
              "facetValues": [
                  {
                      "name": "inactive",
                      "count": 2,
                      "value": "inactive"
                  },
                  {
                      "name": "active",
                      "count": 1,
                      "value": "active"
                  }
              ]
          }
      },
      "qtext": "person"

These search results have been configured to return document extracts and return facet information for the status property by setting query options. This allows visualization of the data with the widget.

React application code

This is the React application code for rendering a search box and a chart:

import { useContext } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, CategoricalChart } from "ml-fasttrack";
  
function App() {
  
  const context = useContext(MarkLogicContext);
  
  const handleSearch = (params) => {
    context.setQtext(params?.q);
  }
 
  const chartConfig = {
    entityTypeConfig: {
        "path": "extracted.content[0].envelope.entityType"
    },
    entities: [
        {
            entityType: 'person',
            items: [
                {
                    path: 'extracted.content[0].envelope',
                    key: 'status'
                }
            ],
        }
    ]
  }
 
  return (
    <div className="App">
      <div>
        <SearchBox onSearch={handleSearch}/>
      </div>
        <div style={{width: '480px'}}>
          <CategoricalChart
            data={context.searchResponse?.results}
            chartType="column"
            config={chartConfig}
            settings={{
              columnChartProps: {
                chartProps: { pannable: true, zoomable: true },
                chartTitleProps: { text: "Statuses" },
                chartSeriesItemProps: { color: "#0cc" }
              }
            }}
            onSeriesClick={(event) => console.log(event)}
          />
        </div>
    </div>
  );
}
  
export default App;

Code explanation

The search results to chart are specified with the data prop. To do this, use the search response object stored in the application context.
The chartType prop specifies a column chart.
The config prop defines what properties in the payload will appear in the chart for each entity type. For configuration details, see API, config API.
The settings prop defines the KendoReact props passed in for configuring the chart. KendoReact props are passed in as objects corresponding to the chart type. For configuration details, see API.

Example rendering

The React application code displays this chart:

Transformed data displayed in a chart.

The CategoricalChart can render a chart that displays facet values from search results. This is similar to displaying facet values using the StringFacet widget but using a chart. The user can click the chart to apply a facet constraint.

Example search results

This example assumes that an application returns these search results:

{
    "total": 3,
    "start": 1,
    "page-length": 10,
    "selected": "include",
    "results": [
        {
            "index": 1,
            "uri": "/person/1001.json",
            "extracted": {
                "kind": "array",
                "content": [
                    {
                        "envelope": {
                            "entityType": "person",
                            "id": 1001,
                            "firstName": "Nerta",
                            "lastName": "Hallwood",
                            "dob": "1985-03-04",
                            "salary": 104000,
                        }
                    }
                ]
            }
        },
        {
            "index": 2,
            "uri": "/person/1002.json",
            "extracted": {
                "kind": "array",
                "content": [
                    {
                        "envelope": {
                            "entityType": "person",
                            "id": 1002,
                            "firstName": "Shaylynn",
                            "lastName": "Guard",
                            "dob": "1964-09-30",
                            "salary": 55000
                        }
                    }
                ]
            }
        },
        {
            "index": 3,
            "uri": "/person/1003.json",
            "extracted": {
                "kind": "array",
                "content": [
                    {
                        "envelope": {
                            "entityType": "person",
                            "id": 1003,
                            "firstName": "Pris",
                            "lastName": "Sizland",
                            "dob": "1988-12-15",
                            "salary": 87000
                        }
                    }
                ]
            }
        }
    ],
    "facets": {
        "status": {
            "type": "xs:string",
            "facetValues": [
                {
                    "name": "inactive",
                    "count": 2,
                    "value": "inactive"
                },
                {
                    "name": "active",
                    "count": 1,
                    "value": "active"
                }
            ]
        }
    },
    "qtext": "person"

React application code

This is the React application code for rendering a search box and a chart:

import { useContext } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, CategoricalChart } from "ml-fasttrack";
  
function App() {
  
  const context = useContext(MarkLogicContext);
  
  const handleSearch = (params) => {
    context.setQtext(params?.q);
  }
 
  const chartFacetConfig = {
    facet: {
        name: "status",
        title: "Status"
    }
  }
 
  const handleChartFacetClick = (event) => {
    context.addStringFacetConstraint({
      type: 'string',
      title: event.target.props.config.facet.title,
      name: event.target.props.config.facet.name,
      value: [event.category]
    })
  }
 
  return (
    <div className="App">
      <div>
        <SearchBox onSearch={handleSearch}/>
      </div>
        <div style={{width: '480px'}}>
          <CategoricalChart
            data={context?.searchResponse?.facets}
            chartType="pie"
            config={chartFacetConfig}
            settings={{
              pieChartProps: {
                chartProps: { pannable:true, zoomable: true },
                chartSeriesItemProps: {
                    labels: {
                        visible: true,
                        content:  (props) => {
                            return `${props.dataItem.category} has ${props.dataItem.value}`
                        }
                    }
                },
                chartLegendProps: {
                    position: 'bottom',
                    visible: true
                }
            }}}
            onSeriesClick={handleChartFacetClick}
          />
        </div>
    </div>
  );
}
  
export default App;

Code explanation

The facet information for the chart is determined by the config prop's facet property. In this example, the status property is charted.
The chartType prop specifies the chart as a pie chart.
The onSeriesClick() event handler is executed when the user clicks a slice in the pie chart. The event handler calls the addStringFacetConstraint() method in the application context to set a facet constraint for the status property. For more details, see API.
The settings prop defines the KendoReact props passed in for configuring the chart. KendoReact props are passed in as objects corresponding to the chart type. For configuration details, see API.

Example rendering

The code in this section renders this chart:

When a user clicks a slice in the pie chart, the application context executes a new search with a facet constraint applied. This updates the chart. The SelectedFacets widget can also be added to provide a way of removing facet constraints.

Avoid unnecessary re-renders

You can avoid unnecessary re-renders of the CategoricalChart widget (for example during MarkLogicContext state updates) by wrapping any callback functions passed in as props with the useCallback hook. For details, see Avoid Unnecessary Re-renders of FastTrack Widgets.

API

Prop	Type	Description
data	object	Data to display in the chart.
config	object	Array of entity configuration objects. Each object determines what data to display from a result for an entity type.
chartType	"area" \| "bar" \| "column" \| "donut" \| "line" \| "radarLine" \| "pie"	The chart type.
settings	object	KendoReact props passed in for configuring the chart. KendoReact props are passed in as objects corresponding to the chart type: `areaChartProps` `barChartProps` `columnChartProps` `donutChartProps` `lineChartProps` `pieChartProps` `radarLineChartProps` For details, see the *ChartProps API table below and the KendoReact Chart documentation.
onPlotAreaClick	function	Callback function triggered when the chart plot area is clicked. See KendoReact ChartProps.
onSeriesClick	function	Callback function triggered when the chart series is clicked. See KendoReact ChartProps.
style	CSSProperties	CSS styles applied to the chart. See KendoReact ChartProps.
transformData	((data: any) => SeriesData[])	Callback function for transforming the data value. Used only when not using a `config` prop. Receives a data object as an argument and returns an array of objects with category and value properties.

config API

Prop	Type	Description
entityTypeConfig	PathConfig	Entity type configuration object.
entityTypeConfig.path	string	Path to the entity type in the search result. Specified using JSONPath.
entities[]	object[]	Array of chart configuration objects for each entity.
entities[].entityType	string	Entity type of the configuration object.
entities[].items[]	PathConfig[]	Array of item configuration objects for the charted data. An array allows for multiple property values in the charted data.
entities[].items[].path	string	Path to the object in the search result with the charted values. Specified using JSONPath.
entities[].items[].key	string	Property key for the charted value.
facet	object	Facet configuration object.
facet.name	string	Name of the facet values displayed in the chart.
facet.title	string	Title of the facet. This value is required for setting facet constraints in the application context.

ChartProps API

Prop	Type	Description
chartProps	object	ChartProps for the KendoReact Chart component.
chartTitleProps	object	ChartTitleProps for the KendoReact Chart component.
chartSeriesProps	object	ChartSeriesProps for the KendoReact Chart component.
chartSeriesItemProps	object	ChartSeriesItemProps for the KendoReact Chart component.
chartSeriesLabelsProps	object	ChartSeriesLabelsProps for the KendoReact Chart component.
chartValueAxisProps	object	ChartValueAxisProps for the KendoReact Chart component.
chartValueAxisItemProps	object	ChartValueAxisItemProps for the KendoReact Chart component.
chartCategoryAxisProps	object	ChartCategoryAxisProps for the KendoReact Chart component.
chartCategoryAxisItemProps	object	ChartCategoryAxisItemProps for the KendoReact Chart component.
chartLegendProps	object	ChartLegendProps for the KendoReact Chart component.
chartTooltipProps	object	ChartTooltipProps for the KendoReact Chart component.
chartSeriesItemTooltipProps	object	ChartSeriesItemTooltipProps for the KendoReact chart component.

Develop with FastTrack