---
title: "Navigator"
enterprise: true
framework: javascript
version: "14.1.0"
---

# Navigator

The Navigator provides controls for users to zoom and pan around a chart. It can also include a Mini Chart to show the entire dataset.

#### Enabling the Navigator

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  AreaSeriesModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  AreaSeriesModule,
  CrosshairModule,
  LegendModule,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  title: {
    text: "Try dragging the Navigator's handles to zoom in",
  },
  subtitle: {
    text: "or the area between them to pan around",
  },
  data: getData(),
  series: [
    {
      type: "area",
      xKey: "date",
      yKey: "Tate Modern",
      fill: "#c16068",
      stroke: "#874349",
    },
    {
      type: "area",
      xKey: "date",
      yKey: "Tate Britain",
      fill: "#a2bf8a",
      stroke: "#718661",
    },
    {
      type: "area",
      xKey: "date",
      yKey: "Tate Liverpool",
      fill: "#ebcc87",
      stroke: "#a48f5f",
    },
    {
      type: "area",
      xKey: "date",
      yKey: "Tate St Ives",
      fill: "#80a0c3",
      stroke: "#5a7088",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      interval: {
        maxSpacing: 200,
      },
    },
    y: {
      type: "number",
      label: {
        formatter: (params) => {
          return params.value / 1000 + "k";
        },
      },
    },
  },
  legend: {
    enabled: false,
  },
  navigator: {
    enabled: true,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function toggleEnabled(value: boolean) {
  options.navigator!.enabled = value;

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).toggleEnabled = toggleEnabled;
}
```

[Live example: Enabling the Navigator](https://www.ag-grid.com/charts/typescript/navigator/examples/navigator)

The Navigator is disabled by default, to enable it add the following config to the chart:

```js
{
    navigator: {
        enabled: true,
    },
}
```

## Save & Restore

The navigator will reflect the zoom state that can be saved, restored and programmatically initialised and modified, using the [Chart State API](https://www.ag-grid.com/charts/javascript/api-state/).

## Mini Chart

The Mini Chart gives an overview of the full data of the chart to provide more context when zoomed in.

#### Mini Chart

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ZoomModule,
} from "ag-charts-enterprise";
import { data } from "./data";

const dateFormatter = new Intl.DateTimeFormat("en-US", {
  day: "numeric",
  month: "short",
  year: "numeric",
});
const numberFormatter = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ZoomModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  title: {
    text: "Market Data",
  },
  subtitle: {
    text: "Last 5 years",
  },
  data: data,
  series: [
    {
      type: "line",
      xKey: "date",
      yKey: "AAPL",
    },
    {
      type: "line",
      xKey: "date",
      yKey: "MSFT",
    },
    {
      type: "line",
      xKey: "date",
      yKey: "AMZN",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      interval: {
        maxSpacing: 200,
      },
      crosshair: {
        label: {
          renderer: ({ value }) => {
            return { text: dateFormatter.format(value) };
          },
        },
      },
    },
    y: {
      type: "number",
      label: {
        formatter: (params) => numberFormatter.format(+params.value),
      },
    },
  },
  legend: {
    enabled: true,
  },
  navigator: {
    enabled: true,
    miniChart: {
      enabled: true,
    },
  },
  zoom: {
    enabled: true,
  },
  initialState: {
    zoom: {
      ratioX: { start: 0.9, end: 1 },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Mini Chart](https://www.ag-grid.com/charts/typescript/navigator/examples/mini-chart)

The Mini Chart is disabled by default, and can be enabled in the `miniChart` options on the Navigator.

```js
{
    navigator: {
        miniChart: {
            enabled: true,
        },
    },
}
```

All series in the main chart will be shown in the Mini Chart. Use the `showInMiniChart` property on each series for finer control.

## Customisation

### Styling the Navigator

The Navigator's `height` is configurable and affects the chart's layout by leaving more or less vertical space for the series.

```js
{
    navigator: {
        height: 50,
    },
}
```

The Navigator component has three subcomponents that can be styled independently:

- `mask` - the range mask.
- `minHandle` - the min drag handle.
- `maxHandle` - the max drag handle.

The range mask shows the portion of the range selected, and the drag handles are used to adjust it.

All subcomponent configs are optional, and have default values that make the Navigator look good in charts with both light and dark backgrounds.

The example below uses various Navigator configs (in a deliberately exaggerated way) to change the following visual attributes of the Navigator:

- the corner radius
- range mask's fill, fill opacity and stroke width
- fill and stroke colours of handles
- width, height and stroke width of the left handle
- the length of the left handle's grip lines and the distance between them

#### Navigator Styling

```ts
import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  AreaSeriesModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ZoomModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  AreaSeriesModule,
  CrosshairModule,
  LegendModule,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ZoomModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  title: {
    text: "Navigator Styling",
  },
  data: getData(),
  series: [
    {
      type: "area",
      xKey: "date",
      yKey: "Tate Modern",
      fill: "#c16068",
      stroke: "#874349",
    },
    {
      type: "area",
      xKey: "date",
      yKey: "Tate Britain",
      fill: "#a2bf8a",
      stroke: "#718661",
    },
    {
      type: "area",
      xKey: "date",
      yKey: "Tate Liverpool",
      fill: "#ebcc87",
      stroke: "#a48f5f",
    },
    {
      type: "area",
      xKey: "date",
      yKey: "Tate St Ives",
      fill: "#80a0c3",
      stroke: "#5a7088",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      interval: {
        maxSpacing: 200,
      },
    },
    y: {
      type: "number",
      label: {
        formatter: (params) => {
          return params.value / 1000 + "k";
        },
      },
    },
  },
  legend: {
    enabled: false,
  },
  navigator: {
    height: 50,
    cornerRadius: 10,
    mask: {
      fill: "red",
      strokeWidth: 2,
      fillOpacity: 0.3,
    },
    minHandle: {
      fill: "yellow",
      stroke: "blue",
      width: 16,
      height: 30,
      strokeWidth: 2,
    },
    maxHandle: {
      fill: "lime",
      stroke: "black",
    },
  },
  initialState: {
    zoom: {
      ratioX: { start: 0.2, end: 0.7 },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Navigator Styling](https://www.ag-grid.com/charts/typescript/navigator/examples/navigator-styling)

### Styling the Mini Chart

#### Mini Chart Styling

```ts
import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ZoomModule,
} from "ag-charts-enterprise";
import { data } from "./data";

const dateFormatter = new Intl.DateTimeFormat("en-US", {
  day: "numeric",
  month: "short",
  year: "numeric",
});
const numberFormatter = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  LineSeriesModule,
  NavigatorModule,
  NumberAxisModule,
  UnitTimeAxisModule,
  ZoomModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  title: {
    text: "Market Data",
  },
  subtitle: {
    text: "Last 5 years",
  },
  data: data,
  series: [
    {
      type: "line",
      xKey: "date",
      yKey: "AAPL",
      marker: {
        enabled: false,
      },
    },
    {
      type: "line",
      xKey: "date",
      yKey: "MSFT",
      marker: {
        enabled: false,
      },
    },
    {
      type: "line",
      xKey: "date",
      yKey: "AMZN",
      marker: {
        enabled: false,
      },
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      interval: {
        maxSpacing: 200,
      },
      crosshair: {
        label: {
          renderer: ({ value }) => {
            return { text: dateFormatter.format(value) };
          },
        },
      },
    },
    y: {
      type: "number",
      label: {
        formatter: (params) => numberFormatter.format(+params.value),
      },
    },
  },
  legend: {
    enabled: true,
  },
  navigator: {
    enabled: true,
    miniChart: {
      enabled: true,
      label: {
        fontSize: 20,
        fontWeight: "bold",
      },
    },
  },
  zoom: {
    enabled: true,
  },
  initialState: {
    zoom: {
      ratioX: { start: 0.9, end: 1 },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);
```

[Live example: Mini Chart Styling](https://www.ag-grid.com/charts/typescript/navigator/examples/mini-chart-styling)

The labels on the Mini Chart axis can be styled using the `label` property. See the [API Reference](#reference-AgChartNavigatorOptions-miniChart) for a list of all available options.

```js
{
    navigator: {
        miniChart: {
            enabled: true,
            label: {
                fontSize: 20,
                fontWeight: 'bold',
            },
        },
    },
}
```

## API Reference

#### Navigator

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| enabled | boolean |  | Whether to show the Navigator. |
| height | PixelSize |  | The height of the Navigator. |
| cornerRadius | number |  | The corner radius used by the Navigator. |
| spacing | PixelSize |  | The distance between the Navigator and the bottom axis of the chart. |
| mask | AgNavigatorMaskOptions |  | Configuration for the Navigator's visible range mask. |
| mask.fill | CssColor |  | The fill colour used by the mask. |
| mask.fillOpacity | Opacity |  | The opacity of the mask's fill in the `[0, 1]` interval, where `0` is effectively no masking. |
| mask.stroke | CssColor |  | The stroke colour used by the mask. |
| mask.strokeWidth | PixelSize |  | The stroke width used by the mask. |
| minHandle | AgNavigatorHandleOptions |  | Configuration for the Navigator's left handle. |
| minHandle.fill | CssColor |  | The fill colour used by the handle. |
| minHandle.stroke | CssColor |  | The stroke colour used by the handle. |
| minHandle.strokeWidth | PixelSize |  | The stroke width used by the handle. |
| minHandle.width | PixelSize |  | The width of the handle. |
| minHandle.height | PixelSize |  | The height of the handle. |
| minHandle.cornerRadius | PixelSize |  | The corner radius of the handle. |
| minHandle.grip | boolean |  | Whether to enable the grip dots. |
| maxHandle | AgNavigatorHandleOptions |  | Configuration for the Navigator's right handle. |
| maxHandle.fill | CssColor |  | The fill colour used by the handle. |
| maxHandle.stroke | CssColor |  | The stroke colour used by the handle. |
| maxHandle.strokeWidth | PixelSize |  | The stroke width used by the handle. |
| maxHandle.width | PixelSize |  | The width of the handle. |
| maxHandle.height | PixelSize |  | The height of the handle. |
| maxHandle.cornerRadius | PixelSize |  | The corner radius of the handle. |
| maxHandle.grip | boolean |  | Whether to enable the grip dots. |
| miniChart | AgNavigatorMiniChartOptions |  | Mini Chart options. |
| miniChart.enabled | boolean |  | Whether to show a Mini Chart in the Navigator. |
| miniChart.series | AgMiniChartSeriesOptions[] |  | Override series used in Mini Chart. |
| miniChart.label | AgNavigatorMiniChartLabelOptions |  | Configuration for the Mini Chart's axis labels. |
| miniChart.label.interval | AgNavigatorMiniChartIntervalOptions |  | Configuration for interval between the Mini Chart's axis labels. |
| miniChart.label.interval.minSpacing | PixelSize |  | Maximum gap in pixels between labels. |
| miniChart.label.interval.maxSpacing | PixelSize |  | Maximum gap in pixels between labels. |
| miniChart.label.interval.values | any[] |  | Array of values in axis units to display as labels along the axis. The values in this array must be compatible with the axis type. |
| miniChart.label.interval.step | number |  | The step value between labels, specified as a number or time interval. If the configured interval results in too many labels given the chart size, it will be ignored. |
| miniChart.label.enabled | boolean |  | Set to `false` to hide the axis labels. |
| miniChart.label.fontStyle | FontStyle |  | The font style to use for the labels. |
| miniChart.label.fontWeight | FontWeight |  | The font weight to use for the labels. |
| miniChart.label.fontSize | FontSize |  | The font size in pixels to use for the labels. |
| miniChart.label.fontFamily | FontFamily \| GoogleFontFamily \| Array<FontFamily \| GoogleFontFamily> |  | The font family to use for the labels. A single family name, or an array of names used as fallbacks. |
| miniChart.label.spacing | PixelSize |  | Spacing in pixels between the axis labels and the Mini Chart. |
| miniChart.label.color | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour to use for the labels. A colour string, or a theme-colour reference object. |
| miniChart.label.avoidCollisions | boolean |  | Avoid axis label collision by automatically reducing the number of labels displayed. If set to `false`, axis labels may collide. |
| miniChart.label.format | string |  | Format string used when rendering labels. |
| miniChart.label.formatter | RichFormatter |  | Function used to render axis labels. If `value` is a number, `fractionDigits` will also be provided, which indicates the number of fractional digits used in the step between intervals; for example, a tick step of `0.0005` would have `fractionDigits` set to `4`. |
| miniChart.padding | PixelSize \| PaddingOptions |  | Configuration for the padding inside the Mini Chart. A number applies uniform padding; an object sets each side. |