Frappe Chart API in Frappe Framework v15

What Is the Frappe Chart API?

The Frappe Chart API is a JavaScript-based charting system used in Frappe Framework v15 to render interactive charts inside the Desk interface. It powers ERPNext dashboards, reports, and custom analytics views using the frappe.Chart class.
The chart system is lightweight, dependency-free, and optimized for ERP dashboards.

Who Should Use the Frappe Chart API?

Target Audience

• ERPNext Developers
• Frappe Framework Developers
• Data & Analytics Engineers
• ERP Consultants

Technical Prerequisites

• Frappe Framework v15
• JavaScript (ES6)
• Basic understanding of reports and dashboards

How Does frappe.Chart Work?

The frappe.Chart class takes a DOM container and a configuration object. It renders charts using SVG and updates dynamically when new data is supplied.

Core Entity: frappe.Chart
Module: Desk
Source File (v15): frappe/public/js/frappe/ui/chart.js

How to Create a Chart in Frappe Framework v15?

Basic Chart Example

let chart = new frappe.Chart("#chart", {
title: "Monthly Sales",
data: {
labels: ["Jan", "Feb", "Mar"],
datasets: [
{
name: "Sales",
values: [120, 150, 180]
}
]
},
type: "line",
height: 250
});

What this does:

This creates a line chart showing monthly sales values inside a Desk page or custom report.

What Chart Types Are Supported in Frappe v15?

Frappe Framework v15 officially supports the following chart types:

These types are internally mapped and validated in the Chart API source.

How Is Chart Data Structured?

data: {
labels: ["Q1", "Q2", "Q3"],
datasets: [
{
name: "Revenue",
values: [300, 450, 500]
}
]
}

Rules

• Labels and values must align in length
• Multiple datasets are supported
• Values must be numeric

How to Update Chart Data Dynamically?

chart.update({
labels: ["Apr", "May", "Jun"],
datasets: [
{
name: "Sales",
values: [200, 220, 260]
}
]
});

This method refreshes the chart without re-rendering the container.

How to Configure Axis and Colors?

colors: ['#4F46E5'],
axisOptions: {
xAxisMode: 'tick',
yAxisMode: 'span',
xIsSeries: true
}

These options control axis behavior and visual styling in Desk dashboards.

How to Use Charts in ERPNext Dashboards?

Charts are commonly used in:

• Dashboard Charts
• Script Reports
• Workspace Analytics
• Custom Desk Pages

They integrate seamlessly with report data sources and filters.

Real-World ERPNext Use Cases

Industry Relevance

• Manufacturing: Production trends
• Finance: Revenue and expense analysis
• Sales: Pipeline performance
• HR: Attendance and hiring metrics

Charts enable decision-makers to visualize real-time business data.

Best Practices for Using Frappe Charts

• Keep datasets small for better performance
• Use clear labels and meaningful titles
• Prefer line charts for trends
• Use bar charts for comparisons
• Avoid mixing unrelated datasets

Common Troubleshooting Scenarios

Chart Not Rendering

• Ensure the container element exists
• Verify the chart type value
• Check for empty datasets

Misaligned Data

• Labels and values must have equal length
• Ensure numeric values only

Advanced Topics

Mixed Axis Charts

type: 'axis-mixed',
datasets: [
{
name: "Orders",
chartType: "bar",
values: [20, 30, 40]
},
{
name: "Revenue",
chartType: "line",
values: [200, 300, 450]
}
]

Axis-mixed charts allow multiple visualizations in one view.

Integration Patterns

• Combine with Query Reports
• Use in Workspace Pages
• Bind with frappe.call for live data
• Embed inside custom Desk modules

Cross-References

• Frappe Report API
• Frappe Workspace
• Frappe Dashboard Charts
• ERPNext Analytics

Official References (Verified)

Chart API Docs (v15)

https://docs.frappe.io/framework/user/en/api/chart

GitHub Source (v15)

https://github.com/frappe/frappe/tree/version-15