Powered by Zoomin Software. For more details please contactZoomin

Develop with FastTrack

Table of Contents

TagCloudFacet

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
Print
  • Last Updated: May 5, 2026
  • 4 minute read
    • MarkLogic Server
    • Documentation

The TagCloudFacet widget displays facet values as a visual tag cloud, where each tag's font size is proportional to its count in the search results. Users can click tags to apply facet constraints to their search.

MarkLogic setup

Faceted search requires a range index on the faceted property. A range index can be added to the database configuration with the MarkLogic Admin Interface or with an API.

After an index is added, a faceted constraint must be configured using query options. In this example, the search application returns facets for the /envelope/entityType property. return-facets is set to true so that facet results are returned:

<?xml version="1.0" encoding="UTF-8"?>
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="entityType">
    <range collation="http://marklogic.com/collation/" facet="true" type="xs:string">
      <path-index>/envelope/entityType</path-index>
      <facet-option>limit=25</facet-option>
    </range>
  </constraint>
  <return-facets>true</return-facets>
</options>

The example code will return this response:

{
  "facets": {
    "entityType": {
      "type": "collection",
      "facetValues": [
        {
          "name": "organization",
          "count": 40,
          "value": "organization"
        },
        {
          "name": "person",
          "count": 100,
          "value": "person"
        },
        {
          "name": "location",
          "count": 25,
          "value": "location"
        }
      ]
    }
  }
  // ...
}

Example rendering

The TagCloudFacet widget renders each facet value as a clickable tag. Tags with higher counts are displayed in a larger font size. Clicking a tag applies the corresponding facet constraint to the search.

TagCloudFacet example configuration

In this example configuration, the TagCloudFacet widget is imported and configured in a React application.

import { useContext } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, ResultsSnippet, TagCloudFacet } from "ml-fasttrack";

function App() {

  const context = useContext(MarkLogicContext);

  const handleSearch = (params) => {
    context.setQtext(params?.q);
  }

  const handleFacetSelect = (selection) => {
    context.addStringFacetConstraint(selection);
  }

  return (
    <div className="App">
      <div>
        <SearchBox onSearch={handleSearch}/>
      </div>
      <div style={{display: 'flex', flexDirection: 'row'}}>
        <div style={{width: '640px'}}>
          <ResultsSnippet
            results={context.searchResponse.results}
            paginationFooter={true}
          />
        </div>
        <div>
          {context?.searchResponse?.facets?.entityType &&
            <TagCloudFacet
              title="Entity Types"
              data={context?.searchResponse?.facets?.entityType}
              name="entityType"
              onSelect={handleFacetSelect}
              minFontSize={12}
              maxFontSize={32}
            />
          }
        </div>
      </div>
    </div>
  );
}

export default App;

Code explanation

In the TagCloudFacet example configuration:

  • The data prop is set to the entityType from the search response object.

  • The onSelect callback receives a Constraint object and is triggered when a tag is clicked.

  • The application can then set the facet constraint in the application context using the addStringFacetConstraint method.

  • minFontSize and maxFontSize control the range of font sizes used to represent tag weights.

Setting and resetting the widget

See the section Setting and resetting facet widgets.

Configuring AND/OR logic

See the section Configuring AND/OR logic for facet widgets.

Configuring NOT logic

The notConfig property of logicConfig enables a NOT operator toggle next to each facet value. When activated, selected values are excluded from search results rather than included.

To enable the NOT toggle with default settings, pass an empty notConfig object:

<TagCloudFacet
  ...
  logicConfig={{
    notConfig: {}
  }}
/>

To combine NOT logic with AND/OR operators:

<TagCloudFacet
  ...
  logicConfig={{
    defaultOperator: 'OR',
    andConfig: {},
    orConfig: {},
    notConfig: {}
  }}
/>

When notConfig is enabled, a "-" button appears beside each facet value. Clicking it toggles that value into a NOT selection, visually indicated with a strikethrough by default. NOT selections generate exclusion constraints in the search query.

TagCloudFacet API

Prop

Type

Description

data

{ type: string; facetValues: { name: string; count: number; value: string; }[]; }

Facet data to display from search results.

name

string

The unique key used to identify this facet. Required if title is not provided.

title

string

Title for the collapsible header. If not provided, name will be used as the facet key.

subTitle

string

Subtitle for the collapsible header.

containerStyle

CSSProperties

CSS styles applied to the widget container.

onSelect

(value: Constraint) => void

Callback function triggered when a tag is clicked.

selectedFacets

Record<string, IFacetValue<string>>

The default selected facets. Used only on the initial render; does not update after the component is mounted.

minFontSize

number

Minimum font size for tags in pixels. Default: 12.

maxFontSize

number

Maximum font size for tags in pixels. Default: 32.

randomize

boolean

Whether to randomize the display order of tags. Default: false.

colorPalette

string | string[]

Color palette for tags. Can be a single color string or an array of colors. If not provided, uses default theme colors.

noDataContent

ReactNode | string

Content displayed if no facetValues were provided.

resetConfig

({ hide?: boolean; label?: string; ButtonProps?: ButtonProps; onReset?: () => void; })

Applies a Reset button to the bottom of the component.

resetConfig.hide

boolean

Whether to hide the Reset button.

resetConfig.label

string

The Reset button label.

resetConfig.ButtonProps

ButtonProps

KendoReact Button props for the Reset button.

resetConfig.onReset

() => void

Callback function triggered when the user clicks the Reset button.

logicConfig

ILogicProps

Configures AND/OR/NOT logic operators for the facet. See Configuring AND/OR logic for facet widgets and Configuring NOT logic above.

logicConfig.notConfig

INotLogicConfig

Enables a NOT toggle on each facet value. When active, the selected values are excluded from search results rather than included.

logicConfig.notConfig.hide

boolean

When true, hides the NOT toggle button. Default: false.

logicConfig.notConfig.label

(isNotted: boolean) => ReactNode

Custom label for the NOT toggle button. Default: '-'.

logicConfig.notConfig.valueStyle

CSSProperties

Style applied to values when the NOT operator is active. Default: { textDecoration: 'line-through' }.

logicConfig.notConfig.ButtonProps

ButtonProps

KendoReact ButtonProps for the NOT toggle button.

ref

const facetRef = useRef(null);

A React ref object that can be used to access the underlying component instance. See Setting and resetting facet widgets.
TitleResults for “How to create a CRG?”Also Available inAlert