---
title: "Financial Charts - Range Buttons"
enterprise: true
framework: javascript
version: "14.1.0"
---

# Financial Charts - Range Buttons

Range Buttons allow the user to easily navigate to specific time periods and ranges along the chart timeline.

> **Note**
>
> Range controls can also be used with any chart type. See [Range Controls](https://www.ag-grid.com/charts/javascript/range-controls/) for more details.

## Range Buttons

#### Range Buttons

```ts
import {
  AgCharts,
  AgFinancialChartOptions,
  ContextMenuModule,
  FinancialChartModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([FinancialChartModule]);

const options: AgFinancialChartOptions = {
  title: { text: "Acme Inc." },
  data: getData(),
  volume: false,
  navigator: true,
};

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

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

[Live example: Range Buttons](https://www.ag-grid.com/charts/typescript/range-buttons/examples/range-buttons)

The Range Buttons are enabled by default for Financial Charts. To hide them, set the `rangeButtons` chart option to `false`.

## Custom Buttons

It is possible to override the default buttons by providing an array of button objects.

#### Custom Range Buttons

```ts
import {
  AgCharts,
  AgFinancialChartOptions,
  ContextMenuModule,
  FinancialChartModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";

const MONTH = 30 * 24 * 60 * 60 * 1000;
ModuleRegistry.registerModules([FinancialChartModule]);

const options: AgFinancialChartOptions = {
  title: { text: "Acme Inc." },
  data: getData(),
  volume: false,
  theme: {
    overrides: {
      common: {
        ranges: {
          enabled: true,
          buttons: [
            {
              label: "6 Months",
              value: 6 * MONTH,
            },
            {
              label: "12 Months",
              value: 12 * MONTH,
            },
            {
              label: "February",
              value: [new Date(2023, 1, 1), new Date(2023, 2, 1)],
            },
            {
              label: "All Data",
              value: ({ start, end }) => [start, end],
            },
          ],
        },
      },
    },
  },
};

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

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

[Live example: Custom Range Buttons](https://www.ag-grid.com/charts/typescript/range-buttons/examples/custom-range-buttons)

Custom buttons can be defined through the `ranges` options object.

```js
{
    ranges: {
        enabled: true,
        buttons: [
            {
                label: '6 Months',
                value: 6 * MONTH,
            },
            {
                label: '12 Months',
                value: 12 * MONTH,
            },
            {
                label: 'February',
                value: [new Date(2023, 1, 1), new Date(2023, 2, 1)],
            },
            {
                label: 'All Data',
                value: ({ start, end }) => [start, end],
            },
        ],
    },
}
```

In this configuration:

- `label` specifies the text displayed on the button.
- `value` determines the time range the button applies:
  - For "6 Months" and "12 Months", it sets the range to the past 6 or 12 months, respectively.
  - For "February", it sets the range to February 2023, from February 1 to March 1.
  - For "All Data", it dynamically sets the range to include all available data from the start to the end date.

## API Reference

#### Range Button Options

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| enableOutOfRange | boolean | false | Whether out of range buttons should be enabled. |
| gap | PixelSize | 0 | The gap between each button. |
| position | 'top-left' \| 'top' \| 'top-right' \| 'bottom-left' \| 'bottom' \| 'bottom-right' | 'top-right' | The position of the range buttons on the chart. |
| spacing | PixelSize | 10 | The spacing between the range buttons and the series area or axis when positioned at the top or bottom, respectively. |
| button | AgRangesButtonStyles |  |  |
| button.cornerRadius | PixelSize |  |  |
| button.padding | PixelSize \| PaddingOptions |  | The padding inside the range buttons. A number applies uniform padding; an object sets each side. |
| button.textColor | CssColor |  |  |
| button.active | AgRangesStateStyles |  |  |
| button.active.textColor | CssColor |  |  |
| button.active.fill | CssColor |  | The colour for filling shapes. |
| button.active.fillOpacity | Opacity |  | The opacity of the fill colour. |
| button.active.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| button.disabled | AgRangesStateStyles |  |  |
| button.disabled.textColor | CssColor |  |  |
| button.disabled.fill | CssColor |  | The colour for filling shapes. |
| button.disabled.fillOpacity | Opacity |  | The opacity of the fill colour. |
| button.disabled.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| button.hover | AgRangesStateStyles |  |  |
| button.hover.textColor | CssColor |  |  |
| button.hover.fill | CssColor |  | The colour for filling shapes. |
| button.hover.fillOpacity | Opacity |  | The opacity of the fill colour. |
| button.hover.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| button.fill | CssColor |  | The colour for filling shapes. |
| button.fillOpacity | Opacity |  | The opacity of the fill colour. |
| button.fontSize | FontSize |  | The size of the font in pixels for text elements. |
| button.fontFamily | FontFamily |  | The font family for text elements. |
| button.fontStyle | FontStyle |  | The style to use for text elements. |
| button.fontWeight | FontWeight |  | The font weight to use for text elements. |
| button.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| button.strokeWidth | PixelSize |  | The width of the stroke in pixels. |
| dropdown | AgRangesDropdown |  |  |
| dropdown.visible | 'auto' \| 'always' \| 'never' | 'auto' | When to swap out the range buttons for a dropdown. |
| dropdown.cornerRadius | PixelSize |  |  |
| dropdown.padding | PixelSize \| PaddingOptions |  | The padding inside the range buttons. A number applies uniform padding; an object sets each side. |
| dropdown.textColor | CssColor |  |  |
| dropdown.active | AgRangesStateStyles |  |  |
| dropdown.active.textColor | CssColor |  |  |
| dropdown.active.fill | CssColor |  | The colour for filling shapes. |
| dropdown.active.fillOpacity | Opacity |  | The opacity of the fill colour. |
| dropdown.active.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| dropdown.disabled | AgRangesStateStyles |  |  |
| dropdown.disabled.textColor | CssColor |  |  |
| dropdown.disabled.fill | CssColor |  | The colour for filling shapes. |
| dropdown.disabled.fillOpacity | Opacity |  | The opacity of the fill colour. |
| dropdown.disabled.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| dropdown.hover | AgRangesStateStyles |  |  |
| dropdown.hover.textColor | CssColor |  |  |
| dropdown.hover.fill | CssColor |  | The colour for filling shapes. |
| dropdown.hover.fillOpacity | Opacity |  | The opacity of the fill colour. |
| dropdown.hover.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| dropdown.fill | CssColor |  | The colour for filling shapes. |
| dropdown.fillOpacity | Opacity |  | The opacity of the fill colour. |
| dropdown.fontSize | FontSize |  | The size of the font in pixels for text elements. |
| dropdown.fontFamily | FontFamily |  | The font family for text elements. |
| dropdown.fontStyle | FontStyle |  | The style to use for text elements. |
| dropdown.fontWeight | FontWeight |  | The font weight to use for text elements. |
| dropdown.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| dropdown.strokeWidth | PixelSize |  | The width of the stroke in pixels. |
| buttons | AgRangesButton[] |  | The buttons to display. |
| buttons.value (required) | number \| AgRangesButtonValuePair \| AgRangesButtonValueFunction \| AgTimeInterval \| AgTimeIntervalUnit \| undefined |  | Timestamp range on which to focus the chart, as either a single start time, a pair of times or a function that returns a pair of times. |
| buttons.enabled | boolean |  | Set to force this button to be enabled or disabled. |
| buttons.icon | AgIconName |  | Icon to display on the button. |
| buttons.label | string |  | Text label to display on the button. |
| buttons.ariaLabel | string |  | Text label to announce in screen readers. |
| buttons.tooltip | string |  | Tooltip text to display on hover over the button. |
| enabled | boolean |  | Whether the associated elements and properties should be used in the chart. |
| cornerRadius | PixelSize |  |  |
| padding | PixelSize \| PaddingOptions |  | The padding inside the range buttons. A number applies uniform padding; an object sets each side. |
| textColor | CssColor |  |  |
| active | AgRangesStateStyles |  |  |
| active.textColor | CssColor |  |  |
| active.fill | CssColor |  | The colour for filling shapes. |
| active.fillOpacity | Opacity |  | The opacity of the fill colour. |
| active.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| disabled | AgRangesStateStyles |  |  |
| disabled.textColor | CssColor |  |  |
| disabled.fill | CssColor |  | The colour for filling shapes. |
| disabled.fillOpacity | Opacity |  | The opacity of the fill colour. |
| disabled.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| hover | AgRangesStateStyles |  |  |
| hover.textColor | CssColor |  |  |
| hover.fill | CssColor |  | The colour for filling shapes. |
| hover.fillOpacity | Opacity |  | The opacity of the fill colour. |
| hover.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| fill | CssColor |  | The colour for filling shapes. |
| fillOpacity | Opacity |  | The opacity of the fill colour. |
| fontSize | FontSize |  | The size of the font in pixels for text elements. |
| fontFamily | FontFamily |  | The font family for text elements. |
| fontStyle | FontStyle |  | The style to use for text elements. |
| fontWeight | FontWeight |  | The font weight to use for text elements. |
| stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| strokeWidth | PixelSize |  | The width of the stroke in pixels. |