---
title: "Financial Charts - Range Buttons"
enterprise: true
framework: vue
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/vue/range-controls/) for more details.

## Range Buttons

#### Range Buttons

```ts
import { createApp, defineComponent, ref } from "vue";
import { AgFinancialCharts } from "ag-charts-vue3";
import type { AgChartOptions } from "ag-charts-types";
import { FinancialChartModule, ModuleRegistry } from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([FinancialChartModule]);

const ChartExample = defineComponent({
  template: `
    <ag-financial-charts
      :options="options"
    />
  `,
  components: {
    "ag-financial-charts": AgFinancialCharts,
  },
  setup(props) {
    const options = ref<AgFinancialChartOptions>({
      title: { text: "Acme Inc." },
      data: getData(),
      volume: false,
      navigator: true,
    });

    return {
      options,
    };
  },
});

createApp(ChartExample).mount("#app");
```

[Live example: Range Buttons](https://www.ag-grid.com/charts/vue3/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 { createApp, defineComponent, ref } from "vue";
import { AgFinancialCharts } from "ag-charts-vue3";
import type { AgChartOptions } from "ag-charts-types";
import { FinancialChartModule, ModuleRegistry } from "ag-charts-enterprise";
import { getData } from "./data";

const MONTH = 30 * 24 * 60 * 60 * 1000;

ModuleRegistry.registerModules([FinancialChartModule]);

const ChartExample = defineComponent({
  template: `
    <ag-financial-charts
      :options="options"
    />
  `,
  components: {
    "ag-financial-charts": AgFinancialCharts,
  },
  setup(props) {
    const options = ref<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],
                },
              ],
            },
          },
        },
      },
    });

    return {
      options,
    };
  },
});

createApp(ChartExample).mount("#app");
```

[Live example: Custom Range Buttons](https://www.ag-grid.com/charts/vue3/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. |