AG Charts reports option misconfiguration and caught runtime errors. Reports go to the browser console or a development overlay, the chart can throw to halt execution, and an event can be raised for each issue.
Severity Levels Copy Link
Each validation issue is reported as one of three severities: error, warning, or deprecation.
consoleOn, showOverlayOn and throwOn each take an array of one or more of these severities, and apply only to the ones listed. An empty array disables that option entirely.
The issueRaised event reports every issue and includes a severity property in the parameters.
Validation Overlay Copy Link
The overlay is opt-in and intended for development. Enable it by using validations.showOverlayOn and providing the severity levels desired.
import {
AgCartesianChartOptions,
AgCharts,
BarSeriesModule,
CategoryAxisModule,
ModuleRegistry,
NumberAxisModule,
} from "ag-charts-community";
ModuleRegistry.registerModules([
BarSeriesModule,
CategoryAxisModule,
NumberAxisModule,
]);
const options: AgCartesianChartOptions = {
title: {
text: "Weekly Sales",
},
data: [
{ day: "Mon", sales: 56 },
{ day: "Tue", sales: 72 },
{ day: "Wed", sales: 64 },
{ day: "Thu", sales: 80 },
{ day: "Fri", sales: 91 },
],
series: [
{
type: "bar",
xKey: "day",
yKey: "sales",
// Invalid on purpose: two out-of-range values, so the overlay lists two warnings.
fillOpacity: 2,
strokeWidth: -5,
},
],
axes: {
x: { type: "category" },
y: { type: "number" },
},
validations: {
showOverlayOn: ["error", "warning"],
},
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
{
validations: {
showOverlayOn: ['error', 'warning'],
},
}In this example:
- Any errors or warnings present would be shown in the overlay, but deprecations would not, since
showOverlayOnonly lists'error'and'warning'. - Issues are grouped and sorted by severity, with a count in each group's heading.
- Each issue shows a message with relevant information to enable easy debugging.
- There is a Copy button for pasting into a bug report and dismissing the overlay hides it without suppressing future issues.
- While shown, the validation overlay takes priority over the loading and no-data overlays.
Console Output Copy Link
Validation issues are written to the browser console by default. Use validations.consoleOn to change which severities are logged, or provide an empty array to disable console output entirely.
import {
AgCartesianChartOptions,
AgCharts,
BarSeriesModule,
CategoryAxisModule,
ModuleRegistry,
NumberAxisModule,
} from "ag-charts-community";
let warningsForwardedToLog = false;
ModuleRegistry.registerModules([
BarSeriesModule,
CategoryAxisModule,
NumberAxisModule,
]);
const options: AgCartesianChartOptions = {
title: {
text: "Weekly Sales",
},
data: [
{ day: "Mon", sales: 56 },
{ day: "Tue", sales: 72 },
{ day: "Wed", sales: 64 },
{ day: "Thu", sales: 80 },
{ day: "Fri", sales: 91 },
],
series: [
{
type: "bar",
xKey: "day",
yKey: "sales",
},
],
axes: {
x: { type: "category" },
y: { type: "number" },
},
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
// Invalid on purpose: opacity must be between 0 and 1, so this raises a validation warning.
function applyInvalidOptions() {
// Forward warnings written to the browser console into `console.log` too, so they're visible
// without opening DevTools. Guarded so repeated clicks don't stack duplicate forwarding.
if (!warningsForwardedToLog) {
const originalWarn = console.warn.bind(console);
console.warn = (...args: unknown[]) => {
originalWarn(...args);
console.log(...args);
};
warningsForwardedToLog = true;
}
const isWarningSelected = (
document.getElementById("console-on-warning") as HTMLInputElement
).checked;
const consoleOn: ("error" | "warning" | "deprecation")[] = isWarningSelected
? ["warning"]
: [];
options.series = [
{ type: "bar", xKey: "day", yKey: "sales", fillOpacity: 2 },
];
options.validations = { consoleOn };
chart.update(options);
}
if (typeof window !== "undefined") {
// Attach external event handlers to window so they can be called from index.html
(<any>window).applyInvalidOptions = applyInvalidOptions;
}
{
validations: {
consoleOn: ['warning'],
},
}In the above example:
- Applying the invalid option with
consoleOn: ['warning']selected logs a warning to the console. - Applying it with
consoleOn: []selected logs nothing.
Throwing on Validation Issues Copy Link
Use validations.throwOn to make the chart throw an exception and fail-fast, instead of warning and falling back to a default. This suits automated workflows (for example, end-to-end test runs or AI-assisted development) where a hard failure should be surfaced for immediate attention.
{
validations: {
throwOn: ['warning'],
},
}- Issues can arise at any point, not just when the chart is created, so a throw may interrupt an update part-way and leave the chart in an inconsistent state. Use
throwOnduring development only, never in production. - Console output still follows
consoleOnand is never suppressed by this option.
Issue Raised Events Copy Link
Subscribe to the validations.issueRaised event to programmatically handle validation issues, for example to log them to a custom system.
import {
AgCartesianChartOptions,
AgChartValidationIssueEvent,
AgCharts,
BarSeriesModule,
CategoryAxisModule,
ModuleRegistry,
NumberAxisModule,
} from "ag-charts-community";
ModuleRegistry.registerModules([
BarSeriesModule,
CategoryAxisModule,
NumberAxisModule,
]);
const options: AgCartesianChartOptions = {
title: {
text: "Weekly Sales",
},
data: [
{ day: "Mon", sales: 56 },
{ day: "Tue", sales: 72 },
{ day: "Wed", sales: 64 },
{ day: "Thu", sales: 80 },
{ day: "Fri", sales: 91 },
],
series: [
{
type: "bar",
xKey: "day",
yKey: "sales",
},
],
axes: {
x: { type: "category" },
y: { type: "number" },
},
validations: {
// Disabled so the only console output is the explicit log below, not also the default warning.
consoleOn: [],
issueRaised: (event: AgChartValidationIssueEvent) => console.log(event),
},
};
options.container = document.getElementById("myChart");
const chart = AgCharts.create(options);
// Invalid on purpose: opacity must be between 0 and 1, so this raises a validation warning.
function applyInvalidOptions() {
options.series = [
{ type: "bar", xKey: "day", yKey: "sales", fillOpacity: 2 },
];
chart.update(options);
}
if (typeof window !== "undefined") {
// Attach external event handlers to window so they can be called from index.html
(<any>window).applyInvalidOptions = applyInvalidOptions;
}
{
validations: {
issueRaised: (event) => console.log(event),
},
}In this example:
- The
issueRaisedevent is logged to the console when invalid options are applied. - Unlike
consoleOn,showOverlayOn, andthrowOn,issueRaisedis not filtered by severity.
API Reference Copy Link
Configuration for how the chart reports invalid configuration and runtime issues.
- consoleOn
AgChartValidationSeverity[]default: ['error', 'warning', 'deprecation'] - The severities to write to the browser console.
- showOverlayOn
AgChartValidationSeverity[]default: [] - The severities to report in an overlay on the chart itself.
- throwOn
AgChartValidationSeverity[]default: [] - The severities that cause the chart to throw instead of warning and falling back to a default. Console output is never suppressed by this option.
- issueRaised
Functiondefault: undefined - Called for each validation issue the chart raises.
Configuration for how the chart reports invalid configuration and runtime issues.
- consoleOn
AgChartValidationSeverity[]default: ['error', 'warning', 'deprecation'] - The severities to write to the browser console.
- showOverlayOn
AgChartValidationSeverity[]default: [] - The severities to report in an overlay on the chart itself.
- throwOn
AgChartValidationSeverity[]default: [] - The severities that cause the chart to throw instead of warning and falling back to a default. Console output is never suppressed by this option.
- issueRaised
Functiondefault: undefined - Called for each validation issue the chart raises.