syncfusion-javascript-circular-chart-3d

# Implementing 3D Circular Charts in Syncfusion TypeScript & JavaScript The Syncfusion Essential JS 2 3D Circular Chart visualizes part-to-whole data as three-dimensional pie and doughnut charts. Use this skill to create, configure, customize, update, export, print, and troubleshoot the `CircularChart3D` component in TypeScript and global JavaScript applications. This skill prioritizes: - Complete, runnable examples. - Correct feature-module injection. - Correct data-field mapping. - Separate TypeScript and JavaScript implementations. - Runtime-safe DOM access. - Explicit chart-to-container attachment. - Clear guidance about when each feature should be used. - Prevention of unsupported properties and incomplete configurations. ## Platform Support ### TypeScript Use TypeScript when the application uses: - The `@syncfusion/ej2-charts` npm package. - TypeScript compilation. - Webpack, Vite, or another module bundler. - Strongly typed data models. - Explicit feature-module injection. - IDE-based type validation. TypeScript imports the required chart classes and modules from: ```typescript @syncfusion/ej2-charts ``` Each enabled feature must be imported and injected before the chart instance is created. Example: ```typescript import { CircularChart3D, PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, CircularChartTooltip3D } from '@syncfusion/ej2-charts'; CircularChart3D.Inject( PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, CircularChartTooltip3D ); ``` ### JavaScript Use global JavaScript when the application uses: - CDN scripts. - Locally stored EJ2 global scripts. - The global `ej` namespace. - Traditional HTML and JavaScript files. - No TypeScript compilation or bundling. The 3D Circular Chart constructor is available through: ```javascript ej.charts.CircularChart3D ``` The global EJ2 chart bundle includes the chart feature modules. Explicit `CircularChart3D.Inject(...)` calls are generally unnecessary when using the complete global bundle. ### Browser Language Level The examples use syntax that is compatible with modern browsers. When strict ES5 compatibility is required: - Use `var` instead of `const` and `let`. - Use traditional functions instead of arrow functions. - Avoid optional chaining. - Avoid object spread syntax. - Transpile modern syntax when necessary. ## When to Use This Skill Use this skill when the task requires any of the following: - Creating a basic 3D pie chart. - Creating a 3D doughnut chart. - Switching between pie and doughnut presentations. - Binding local or dynamically updated data. - Mapping category and numeric fields. - Configuring chart dimensions. - Adding titles and subtitles. - Controlling tilt, rotation, depth, or interactive rotation. - Enabling and formatting data labels. - Positioning labels inside or outside segments. - Customizing connector lines. - Mapping custom data-label text. - Handling empty or missing point values. - Configuring legends. - Enabling and formatting tooltips. - Applying templates. - Selecting themes and colors. - Enabling RTL layout. - Configuring animation. - Improving chart accessibility. - Exporting the chart. - Printing the chart. - Handling chart events. - Updating chart properties at runtime. ## Implementation Rules ### Rule 1: Validate Imports Before Generating TypeScript Determine every feature enabled in the chart before writing the import statement. Feature-to-module mapping: ```text 3D pie or doughnut series -> PieSeries3D Data labels -> CircularChartDataLabel3D Legend -> CircularChartLegend3D Tooltip -> CircularChartTooltip3D Export -> CircularChartExport3D ``` If a feature appears in the chart configuration, its corresponding module must be imported and injected. ### Rule 2: Inject Modules Before Creating the Chart Correct: ```typescript CircularChart3D.Inject( PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, CircularChartTooltip3D ); const chart: CircularChart3D = new CircularChart3D({ // Configuration }); ``` Incorrect: ```typescript const chart: CircularChart3D = new CircularChart3D({ // Configuration }); CircularChart3D.Inject( PieSeries3D, CircularChartDataLabel3D ); ``` ### Rule 3: Keep Imports and Injection Synchronized Every injected module must be imported. Every imported feature module should be injected when that feature is used. Correct: ```typescript import { CircularChart3D, PieSeries3D, CircularChartLegend3D } from '@syncfusion/ej2-charts'; CircularChart3D.Inject( PieSeries3D, CircularChartLegend3D ); ``` ### Rule 4: Use Explicit DOM Attachment Create the chart first and then call `appendTo`. ```typescript const chart: CircularChart3D = new CircularChart3D({ // Configuration }); chart.appendTo('#chart'); ``` Use the same pattern in JavaScript: ```javascript var chart = new ej.charts.CircularChart3D({ // Configuration }); chart.appendTo('#chart'); ``` ### Rule 5: Ensure the Host Element Exists Required HTML: ```html <div id="chart"></div> ``` Required attachment: ```typescript chart.appendTo('#chart'); ``` The selector must match the host element ID exactly. ### Rule 6: Keep Data Mapping Synchronized For this data: ```typescript const data = [ { browser: 'Chrome', share: 62.92 } ]; ``` Use: ```typescript series: [{ dataSource: data, xName: 'browser', yName: 'share' }] ``` Do not use: ```typescript xName: 'x', yName: 'y' ``` unless the data objects actually contain `x` and `y` properties. ### Rule 7: Use `subTitle`, Not `subtitle` Correct: ```typescript subTitle: '2023' ``` Incorrect: ```typescript subtitle: '2023' ``` ### Rule 8: Use Full Examples A runnable TypeScript example should include: ```text Imports Module injection Typed data Chart configuration appendTo call Required HTML host ``` A runnable global JavaScript example should include: ```text Valid script references Data Chart configuration appendTo call Required HTML host ``` ## Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) Use this reference for: - Package installation. - TypeScript project setup. - Global JavaScript setup. - CDN and local script loading. - HTML host creation. - Initial chart configuration. - Module injection. - Chart startup and testing. - Common initialization errors. ### Pie and Doughnut Charts 📄 **Read:** [references/pie-and-doughnut-charts.md](references/pie-and-doughnut-charts.md) Use this reference for: - Pie chart fundamentals. - Doughnut chart configuration. - `innerRadius` behavior. - Outer-radius customization. - Various-radius charts. - Runtime pie-to-doughnut switching. - Segment colors. - Segment explosion. - Series opacity. - Pie versus doughnut selection guidance. ### Data Labels 📄 **Read:** [references/data-labels.md](references/data-labels.md) Use this reference for: - Enabling data labels. - Required data-label module injection. - Inside and outside label positions. - Label background, border, and font. - Connector lines. - Label templates. - Text mapping through `name`. - Number and text formatting. - Label rotation. - Dynamic customization through `textRender`. ### Legends, Tooltips and Titles 📄 **Read:** [references/legends-tooltips-and-titles.md](references/legends-tooltips-and-titles.md) Use this reference for: - Legend module injection. - Legend visibility. - Legend position and alignment. - Legend appearance and dimensions. - Legend interaction. - Tooltip module injection. - Tooltip format and templates. - Tooltip appearance and animation. - Title and subtitle configuration. - Title, subtitle, legend, and tooltip text styles. - Legend and tooltip events. ### Styling, Customization and Export 📄 **Read:** [references/styling-customization-and-export.md](references/styling-customization-and-export.md) Use this reference for: - Tilt, rotation, and depth. - Interactive rotation. - Built-in themes. - Series palettes. - Data-driven point colors. - Chart background and border. - RTL support. - Series animation. - Image export. - PDF export. - Print behavior. - Export and print validation. ### Empty Points and Accessibility 📄 **Read:** [references/empty-points-and-accessibility.md](references/empty-points-and-accessibility.md) Use this reference for: - Empty values. - Gap, Drop, Zero, and Average modes. - Empty-point fill and border. - Runtime mode switching. - Chart accessibility settings. - Series accessibility settings. - Keyboard focus. - Accessible descriptions. - Alternative data tables. - Screen-reader testing. - Text and non-text contrast. - Avoiding color-only communication. ## Quick Start ## TypeScript Quick Start ### Required HTML ```html <div id="chart"></div> ``` ### Complete TypeScript ```typescript import { CircularChart3D, PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, CircularChartTooltip3D } from '@syncfusion/ej2-charts'; CircularChart3D.Inject( PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, CircularChartTooltip3D ); interface BrowserData { browser: string; share: number; } const data: BrowserData[] = [ { browser: 'Chrome', share: 62.92 }, { browser: 'Firefox', share: 15.23 }, { browser: 'Safari', share: 19.97 }, { browser: 'Others', share: 2.88 } ]; const chart: CircularChart3D = new CircularChart3D({ width: '100%', height: '500px', title: 'Browser Market Share', subTitle: '2023', tilt: -45, rotation: 0, depth: 50, legendSettings: { visible: true, position: 'Right', alignment: 'Center' }, tooltip: { enable: true, format: '${point.x}: <b>${point.y:n2}%</b>' }, series: [{ name: 'Market Share', dataSource: data, xName: 'browser', yName: 'share', radius: '80%', innerRadius: '0%', dataLabel: { visible: true, position: 'Outside', name: 'browser', connectorStyle: { length: '40px', width: 1, color: '#666666' } } }] }); chart.appendTo('#chart'); ``` ### Runtime Behavior ```text 1. PieSeries3D renders a solid 3D pie. 2. The browser field supplies category names. 3. The share field controls segment angles. 4. CircularChartDataLabel3D renders outside labels. 5. CircularChartLegend3D renders the legend. 6. CircularChartTooltip3D renders hover information. 7. The title and subtitle describe the visualization. 8. appendTo attaches the chart to the HTML host. ``` ## JavaScript Quick Start ### Complete CDN HTML ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>3D Circular Chart</title> <script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-base/dist/global/ej2-base.min.js"></script> <script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-data/dist/global/ej2-data.min.js"></script> <script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-svg-base/dist/global/ej2-svg-base.min.js"></script> <script src="https://cdn.syncfusion.com/ej2/34.2.2/ej2-charts/dist/global/ej2-charts.min.js"></script> </head> <body> <div id="chart"></div> <script src="index.js"></script> </body> </html> ``` ### Complete JavaScript ```javascript var data = [ { browser: 'Chrome', share: 62.92 }, { browser: 'Firefox', share: 15.23 }, { browser: 'Safari', share: 19.97 }, { browser: 'Others', share: 2.88 } ]; var chart = new ej.charts.CircularChart3D({ width: '100%', height: '500px', title: 'Browser Market Share', subTitle: '2023', tilt: -45, rotation: 0, depth: 50, legendSettings: { visible: true, position: 'Right', alignment: 'Center' }, tooltip: { enable: true, format: '${point.x}: <b>${point.y:n2}%</b>' }, series: [{ name: 'Market Share', dataSource: data, xName: 'browser', yName: 'share', radius: '80%', innerRadius: '0%', dataLabel: { visible: true, position: 'Outside', name: 'browser', connectorStyle: { length: '40px', width: 1, color: '#666666' } }