TimelineFacet

Save PDF

Last Updated: May 5, 2026
4 minute read

MarkLogic Server
Documentation

The TimelineFacet widget displays a visual bar-chart timeline for a faceted date property in search results. Users can drag to select a date range on the timeline to constrain the results.

MarkLogic setup

Faceted search on date properties requires a range index on the faceted date 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/publishDate 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="publishDate">
    <range facet="true" type="xs:date">
      <path-index>/envelope/publishDate</path-index>
      <facet-option>limit=100</facet-option>
    </range>
  </constraint>
  <return-facets>true</return-facets>
</options>

The example code will return this response:

{
  "facets": {
    "publishDate": {
      "type": "date",
      "facetValues": [
        {
          "name": "2023-01",
          "count": 45,
          "value": "2023-01-15T00:00:00"
        },
        {
          "name": "2023-02",
          "count": 32,
          "value": "2023-02-15T00:00:00"
        },
        {
          "name": "2023-03",
          "count": 67,
          "value": "2023-03-15T00:00:00"
        }
      ]
    }
  }
  // ...
}

Example rendering

The TimelineFacet widget renders a bar chart showing document counts per date period. Users can drag across the timeline to select a date range. The selected range is highlighted, and the start/end dates are displayed below the timeline. Clicking the date pickers above the timeline also allows setting precise start and end dates.

TimelineFacet example configuration

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

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

function App() {

  const context = useContext(MarkLogicContext);

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

  const handleTimelineSelect = (currentFacet, previousFacet, range) => {
    currentFacet.forEach(constraint => {
      context.addRangeFacetConstraint(constraint);
    });
  }

  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?.publishDate &&
            <TimelineFacet
              title="Publication Date"
              data={context?.searchResponse?.facets?.publishDate}
              name="publishDate"
              onSelect={handleTimelineSelect}
              granularity="month"
              dateFormat="yyyy-MM-dd"
              containerStyle={{ width: '500px' }}
            />
          }
        </div>
      </div>
    </div>
  );
}

export default App;

Code explanation

In the TimelineFacet example configuration:

The data prop is set to the date facet from the search response object.
The onSelect callback receives currentFacet, previousFacet, and range parameters. The currentFacet array contains constraint objects for the selected start and end dates.
The granularity prop controls how date data is aggregated for display (day, week, month, quarter, or year).
The dateFormat prop specifies the format string used when building constraint values, following date-fns conventions.

See the section Setting and resetting facet widgets.

TimelineFacet API

Prop	Type	Description
data	{ type: string; facetValues: { name: string; count: number; value: string \| Date; }[]; }	Facet data containing the date values and counts to display.
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	(currentFacet: ITimelineFacetConstraint[], previousFacet: ITimelineFacetConstraint[], value: SelectionRange) => void	Callback function triggered when the user selects a date range. Receives the current constraints, previous constraints, and the raw selection range.
dateFormat	string	Format string for the returned date values, following date-fns conventions. Default: `"yyyy-MM-dd"`.
options	{ locale?, weekStartsOn?, firstWeekContainsDate?, useAdditionalWeekYearTokens?, useAdditionalDayOfYearTokens? }	date-fns format function options.
startOperator	Operators	Operator applied to the range start value. Default: `'GE'`.
endOperator	Operators	Operator applied to the range end value. Default: `'LE'`.
height	string \| number	Height of the timeline visualization. Default: `'120px'`.
barColor	string	Color for the unselected timeline bars. Default: `'#1976d2'`.
selectionColor	string	Background color for the selected range region. Default: `'rgba(25, 118, 210, 0.2)'`.
selectedBarColor	string	Color for bars within the selected range. Default: `'#4caf50'`.
showCounts	boolean	Whether to show count values on top of the bars. Default: `false`.
showDateLabels	boolean	Whether to show date labels below the timeline. Default: `true`.
labelFormat	string	date-fns format string for the date labels displayed below the timeline. Default: `'MMM yyyy'`.
minDate	Date	Minimum date to display on the timeline. If not provided, uses the minimum date from the data.
maxDate	Date	Maximum date to display on the timeline. If not provided, uses the maximum date from the data.
allowBrushSelection	boolean	Whether to allow drag-to-select range behavior. Default: `true`.
showSelectionText	boolean	Whether to display the current selection as text below the timeline. Default: `true`.
granularity	'day' \| 'week' \| 'month' \| 'quarter' \| 'year'	Aggregation granularity for the timeline bars. Default: `'month'`.
removeAccordion	boolean	When `true`, the component is not wrapped in a collapsible panel. Default: `false`.
resetConfig	({ hide?: boolean; label?: string; ButtonProps?: ButtonProps; onReset?: (currentFacet, previousFacet, value) => 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	(currentFacet: ITimelineFacetConstraint[], previousFacet: ITimelineFacetConstraint[], value: SelectionRange) => void	Callback function triggered when the user clicks the Reset 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.

Develop with FastTrack

TimelineFacet

Table of Contents

TimelineFacet

MarkLogic setup

Example rendering

TimelineFacet example configuration

Code explanation

Setting and resetting the widget

TimelineFacet API