--- product: "AG Charts" title: "Background Regions" description: "Shade a rectangular area of the Angular Chart series area, bounded by value ranges on the x and y axes. Add labels and customise fills and strokes." enterprise: true framework: angular version: "14.2.0" related: - title: "Cross Lines" url: "https://www.ag-grid.com/charts/angular/axes-cross-lines/" - title: "Legend" url: "https://www.ag-grid.com/charts/angular/legend/" - title: "Formatters" url: "https://www.ag-grid.com/charts/angular/formatters/" - title: "Stylers" url: "https://www.ag-grid.com/charts/angular/stylers/" - title: "Series Bars" url: "https://www.ag-grid.com/charts/angular/bars/" - title: "Series Fills" url: "https://www.ag-grid.com/charts/angular/fills/" - title: "Series Labels" url: "https://www.ag-grid.com/charts/angular/series-labels/" - title: "Series Markers" url: "https://www.ag-grid.com/charts/angular/markers/" - title: "Style Segments" url: "https://www.ag-grid.com/charts/angular/style-segments/" - title: "Annotations" url: "https://www.ag-grid.com/charts/angular/annotations/" - title: "Colour Scale" url: "https://www.ag-grid.com/charts/angular/colour-scale/" - title: "Error Bars" url: "https://www.ag-grid.com/charts/angular/error-bars/" llms: "https://www.ag-grid.com/charts/llms.txt" --- # Background Regions Background Regions are shaded rectangular areas in a cartesian chart, bounded by value ranges on both the x and y axes. These can denote additional information or thresholds, making them useful for data analysis. ## Adding Background Regions Background Regions are defined in the `seriesArea.backgroundRegions` array. #### Simple Background Region ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Simple Background Region](https://www.ag-grid.com/charts/angular/background-regions/examples/simple-background-regions/) ```js { seriesArea: { backgroundRegions: [ { xRange: { start: new Date(2025, 5, 1), end: new Date(2025, 8, 1) }, yRange: { start: 0, end: 50 }, label: { text: 'Drought Risk', }, }, ], }, } ``` In this configuration: - `xRange` and `yRange` bound the region with `start` and `end` values, given in the units of the appropriate axis. - `label.text` adds a [label](https://www.ag-grid.com/charts/angular/background-regions/#labels) to the region. Regions are drawn behind the series and above the chart background. ## Range Bounds The range boundaries are defined by optional `xRange` and `yRange` properties, each containing optional `start` and `end` properties. These must be in the units of the appropriate axis. Omitting a `start` or an `end` extends that side of the region along the entire axis domain in that direction. Omitting a range entirely spans the entire axis. #### Range Bounds ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Range Bounds](https://www.ag-grid.com/charts/angular/background-regions/examples/range-bounds/) ```js { seriesArea: { backgroundRegions: [ { xRange: { start: new Date(2025, 5, 1) }, yRange: { end: 50 }, label: { text: 'Drought Risk', }, }, ], }, } ``` In this configuration: - "Open Ended" has only one bound defined for each range. - `xRange` has no `end`, so the region extends to the right edge of the series area. - `yRange` has no `start`, so it extends to the bottom edge. - "Both Bounds" has both `start` and `end` defined for `xRange` and `yRange`, so the region is bounded on all sides. - "Full Width" has no `xRange`, so it spans the full width of the series area, while `yRange` is bounded on both sides. - Values outside the axis domain are clamped to the edge of the series area. ## Labels Use `label.position` to place a label relative to its region. #### Labels ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Labels](https://www.ag-grid.com/charts/angular/background-regions/examples/region-labels/) ```js { seriesArea: { backgroundRegions: [ { xRange: { start: new Date(2025, 5, 1), end: new Date(2025, 8, 1) }, yRange: { start: 20, end: 50 }, label: { text: 'Drought Risk', position: 'top', }, }, ], }, } ``` In this example: - Use the dropdown to change `position`. - Position names give the edge first, then the alignment along it. `top-left` sits above the region, aligned left, and `left-top` sits to its left, aligned top. - An `inside` prefix places the label within the region. - `xOffset` and `yOffset` move the label from its position by the specified number of pixels. ## Multiple Axes On a chart with [multiple axes](https://www.ag-grid.com/charts/angular/axes-secondary/) in one direction, use `axis` to specify the axis that the range is plotted against. #### Multiple Axes ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Multiple Axes](https://www.ag-grid.com/charts/angular/background-regions/examples/multiple-axes/) ```js { seriesArea: { backgroundRegions: [ { xRange: { start: new Date(2025, 0, 1), end: new Date(2025, 4, 1) }, yRange: { axis: 'rainfall', start: 100 }, label: { text: 'Heavy Rainfall', position: 'inside-top-left', }, }, ], }, axes: { x: { type: 'unit-time' }, capacity: { type: 'number', position: 'left' }, rainfall: { type: 'number', position: 'right' }, }, } ``` In this example: - `yRange.axis` is set to `'rainfall'`, so the range is resolved against that axis rather than the `capacity` axis. - `yRange` has no `end`, so the region extends to the top edge of the series area. - When `axis` is omitted in this scenario, the range uses the first axis declared in that direction. ## Customisation Regions are styled with `fill`, `fillOpacity`, `stroke`, `strokeWidth` and `strokeOpacity`. [Labels](https://www.ag-grid.com/charts/angular/background-regions/#labels) are styled with [font](https://www.ag-grid.com/charts/angular/text/) and [fills & border](https://www.ag-grid.com/charts/angular/fills-borders/) options. #### Customisation ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Customisation](https://www.ag-grid.com/charts/angular/background-regions/examples/customisation/) ```js { seriesArea: { backgroundRegions: [ { fill: '#5090dc', fillOpacity: 0.2, stroke: { ref: 'foregroundColor', mix: 0.35, ontoColor: '#5090dc' }, strokeWidth: 2, xRange: { start: 14, end: 31 }, yRange: { start: 27500, end: 63000 }, label: { text: 'Retail', position: 'top-left', yOffset: -4, color: { ref: 'foregroundColor', mix: 0.35, ontoColor: '#5090dc' }, fontSize: 13, fontWeight: 'bold', fill: { ref: 'backgroundColor' }, fillOpacity: 0.85, cornerRadius: 4, padding: { top: 4, right: 8, bottom: 4, left: 8 }, border: { enabled: true, stroke: { ref: 'foregroundColor', mix: 0.35, ontoColor: '#5090dc' }, }, }, }, //... other regions ], }, } ``` In this example: - Each market segment has a region covering the middle 80% of its deals on each axis, with a `fill` matching the series colour. - Each label is colour-matched to its region, with `fill`, `cornerRadius`, `padding` and `border` styling the box around the text and `color` styling the text itself. Colours are set with [theme parameters](https://www.ag-grid.com/charts/angular/colours/#theme-parameter-references) so they adapt to light and dark themes. - `yOffset` lifts each label 4px clear of its region. ## API Reference #### Background Region | Property | Type | Default | Description | | --- | --- | --- | --- | | xRange | AgSeriesAreaBackgroundRegionRange | | The bounds of the region on an x-axis. Omit to span the full width of the series area. | | xRange.axis | string | | The key of the axis in the `axes` dictionary that this range applies to. | | xRange.start | AxisValue | | The axis value where the region starts. Omit to extend the region to the edge of the series area. | | xRange.end | AxisValue | | The axis value where the region ends. Omit to extend the region to the edge of the series area. | | yRange | AgSeriesAreaBackgroundRegionRange | | The bounds of the region on a y-axis. Omit to span the full height of the series area. | | yRange.axis | string | | The key of the axis in the `axes` dictionary that this range applies to. | | yRange.start | AxisValue | | The axis value where the region starts. Omit to extend the region to the edge of the series area. | | yRange.end | AxisValue | | The axis value where the region ends. Omit to extend the region to the edge of the series area. | | label | AgSeriesAreaBackgroundRegionLabel | | Configuration for the label displayed with the region. | | label.fontFamily | FontFamily \| GoogleFontFamily \| Array | | The font family to use for the label. A single family name, or an array of names used as fallbacks. | | label.position | AgSeriesAreaBackgroundRegionLabelPosition | | The position of the Background Region label. | | label.rotation | Degree | | The rotation of the Background Region label in degrees. | | label.text | string | | The text to show in the label. | | label.xOffset | PixelSize | 0 | The horizontal offset in pixels for the label. | | label.yOffset | PixelSize | 0 | The vertical offset in pixels for the label. | | label.enabled | boolean | | Whether the associated elements and properties should be used in the chart. | | label.color | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor | | The colour for text elements. A colour string, or a theme-colour reference object. | | label.fontSize | FontSize | | The size of the font in pixels for text elements. | | label.fontStyle | FontStyle | | The style to use for text elements. | | label.fontWeight | FontWeight | | The font weight to use for text elements. | | label.border | BorderOptions | | Stroke options for the box border. | | label.border.enabled | boolean | | Whether the associated elements and properties should be used in the chart. | | label.border.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor | | The colour for the stroke. | | label.border.strokeWidth | PixelSize | | The width of the stroke in pixels. | | label.border.strokeOpacity | Opacity | | The opacity of the stroke colour. | | label.cornerRadius | PixelSize | | Apply rounded corners to the label box. | | label.padding | PixelSize \| PaddingOptions | | Distance between the label text and the border. A number applies uniform padding; an object sets each side. | | label.fill | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor \| AgGradientColor \| AgPatternColor \| AgImageFill | | The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill. | | label.fillOpacity | Opacity | | The opacity of the fill colour. | | fill | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor \| AgGradientColor \| AgPatternColor \| AgImageFill | | The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill. | | fillOpacity | Opacity | | The opacity of the fill colour. | | stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor | | The colour for the stroke. | | strokeWidth | PixelSize | | The width of the stroke in pixels. | | strokeOpacity | Opacity | | The opacity of the stroke colour. | #### Range | Property | Type | Default | Description | | --- | --- | --- | --- | | axis | string | | The key of the axis in the `axes` dictionary that this range applies to. | | start | AxisValue | | The axis value where the region starts. Omit to extend the region to the edge of the series area. | | end | AxisValue | | The axis value where the region ends. Omit to extend the region to the edge of the series area. | #### Label | Property | Type | Default | Description | | --- | --- | --- | --- | | fontFamily | FontFamily \| GoogleFontFamily \| Array | | The font family to use for the label. A single family name, or an array of names used as fallbacks. | | position | AgSeriesAreaBackgroundRegionLabelPosition | | The position of the Background Region label. | | rotation | Degree | | The rotation of the Background Region label in degrees. | | text | string | | The text to show in the label. | | xOffset | PixelSize | 0 | The horizontal offset in pixels for the label. | | yOffset | PixelSize | 0 | The vertical offset in pixels for the label. | | enabled | boolean | | Whether the associated elements and properties should be used in the chart. | | color | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor | | The colour for text elements. A colour string, or a theme-colour reference object. | | fontSize | FontSize | | The size of the font in pixels for text elements. | | fontStyle | FontStyle | | The style to use for text elements. | | fontWeight | FontWeight | | The font weight to use for text elements. | | border | BorderOptions | | Stroke options for the box border. | | border.enabled | boolean | | Whether the associated elements and properties should be used in the chart. | | border.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor | | The colour for the stroke. | | border.strokeWidth | PixelSize | | The width of the stroke in pixels. | | border.strokeOpacity | Opacity | | The opacity of the stroke colour. | | cornerRadius | PixelSize | | Apply rounded corners to the label box. | | padding | PixelSize \| PaddingOptions | | Distance between the label text and the border. A number applies uniform padding; an object sets each side. | | fill | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor \| AgGradientColor \| AgPatternColor \| AgImageFill | | The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill. | | fillOpacity | Opacity | | The opacity of the fill colour. |