syncfusion-javascript-bullet-chart

# Implementing Bullet Charts in Syncfusion TypeScript & JavaScript The Syncfusion EJ2 Bullet Chart is a specialized visualization component for comparing actual values against target values within a quantitative scale. Qualitative ranges can provide performance context such as below expectations, approaching target, and target achieved. The Bullet Chart supports: - Single and multiple performance measures. - Actual-value bars. - One or more target markers. - Qualitative performance ranges. - Horizontal and vertical orientations. - Major and minor scale ticks. - Numeric and category labels. - Data labels for actual values. - Tooltip templates. - Animation. - Themes. - Right-to-left rendering. - Browser printing. - Dynamic data updates. - Accessibility and keyboard support. ## Platform Support This skill covers both TypeScript and JavaScript implementations. ### TypeScript TypeScript implementations use: - npm package installation. - Imports from `@syncfusion/ej2-charts`. - Feature-module injection through `BulletChart.Inject(...)`. - Typed data interfaces. - Typed application event handlers. - A bundler such as webpack or Vite. - IDE and compiler support. ### JavaScript JavaScript implementations use: - A consolidated EJ2 CDN script. - Individual CDN package scripts when required. - Locally hosted ES5 scripts where required. - The global `ej.charts` namespace. - Feature-module injection through `ej.charts.BulletChart.Inject(...)`. - No TypeScript compilation step. The configuration model is generally equivalent between TypeScript and JavaScript. Package loading, imports, typing, module injection, and event-listener syntax differ between platforms. ## When to Use This Skill Use this skill when you need to: - **Display performance metrics:** Compare actual values with targets. - **Build KPI dashboards:** Monitor sales, revenue, quality, completion, service levels, or operational metrics. - **Display multiple measures:** Show related performance records with category labels. - **Configure targets:** Display one or more comparative markers. - **Configure qualitative ranges:** Define performance zones such as poor, satisfactory, good, and excellent. - **Customize actual and target measures:** Configure shapes, colors, borders, thickness, and target-marker styles. - **Configure the scale:** Set minimum, maximum, interval, tick placement, label placement, and number formatting. - **Display actual-value labels:** Enable and style Bullet Chart data labels. - **Add tooltips:** Display actual and target values through tooltip templates. - **Support dynamic updates:** Replace data, refresh performance values, and implement polling. - **Customize layout:** Configure orientation, dimensions, responsive behavior, themes, and RTL rendering. - **Print or download output:** Print the report or serialize the rendered SVG for an application-owned download. - **Support accessibility:** Provide keyboard focus, semantic summaries, data tables, contrast, RTL, and live announcements. ## Component Selection Use `BulletChart` when the visualization must compare an actual value against one or more targets within qualitative ranges. Use a regular Cartesian `Chart` instead when the requirement involves: - Value trends over time. - Grouped or stacked comparisons. - Logarithmic axes. - Point selection. - Zooming and panning. - Crosshairs. - Multiple independent axes. - Series-level interactions. - Regular Chart export modules. Use `StockChart` when the application requires a stock-focused financial interface with built-in range selection and period controls. ## Navigation Guide Read only the reference files relevant to the requested task. ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) for: - Package installation. - TypeScript setup. - JavaScript CDN setup. - Basic Bullet Chart creation. - Initial data binding. - Tooltip injection. - Container sizing. - Common setup issues. ### Value Bar & Comparative Bar 📄 **Read:** [references/value-bar-and-comparative-bar.md](references/value-bar-and-comparative-bar.md) for: - Actual-value bar configuration. - `Rect` and `Dot` actual-bar shapes. - Actual-bar color mapping. - Actual-bar height and border. - Comparative-marker shapes. - Comparative-marker color and width. - Multiple targets. - Performance-based coloring. - Dynamic bar updates. ### Ranges & Qualitative Scale 📄 **Read:** [references/ranges-and-qualitative-scale.md](references/ranges-and-qualitative-scale.md) for: - Qualitative range boundaries. - Range colors and opacity. - Named ranges. - Range legends and shapes. - Dynamic ranges. - Shared scale requirements. - Performance-zone examples. - Accessible range descriptions. ### Axis Customization 📄 **Read:** [references/axis-customization.md](references/axis-customization.md) for: - Minimum, maximum, and interval. - Major and minor ticks. - Tick placement. - Numeric-label formatting. - Numeric-label placement. - Category-label styling. - Group separators. - Opposed positioning. - Scale and orientation behavior. ### Data Binding & Labels 📄 **Read:** [references/data-binding-and-labels.md](references/data-binding-and-labels.md) for: - Actual, target, and category mappings. - Local and remote data. - Data validation. - Multiple targets. - Dynamic updates. - Real-time data. - API polling. - Actual-value data labels. - Category labels. - Multiple measures. - Accessible summaries and tables. ### Title, Tooltip & Interactivity 📄 **Read:** [references/title-tooltip-and-interactivity.md](references/title-tooltip-and-interactivity.md) for: - Title and subtitle configuration. - Title styling and positioning. - Tooltip module injection. - Tooltip templates. - Tooltip appearance. - Bullet Chart lifecycle events. - Chart-click handling. - Application-owned drill-down controls. - Dynamic title and tooltip updates. ### Customization, Dimensions & Export 📄 **Read:** [references/customization-dimensions-and-export.md](references/customization-dimensions-and-export.md) for: - Horizontal and vertical orientations. - Right-to-left rendering. - Animation and reduced motion. - Themes. - Fixed and percentage dimensions. - Responsive layouts. - SVG serialization. - SVG-to-PNG conversion. - Printing. - Browser Save as PDF workflows. ### Accessibility 📄 **Read:** [references/accessibility.md](references/accessibility.md) for: - WCAG and Section 508 considerations. - Generated WAI-ARIA output. - Documented keyboard interaction. - Keyboard focus. - Semantic text alternatives. - Data tables. - Dynamic update announcements. - Color and contrast. - RTL accessibility. - Automated and manual testing. ## Core Implementation Rules ### Use BulletChart Import: ```typescript import { BulletChart } from '@syncfusion/ej2-charts'; ``` Create the instance: ```typescript const bulletChart: BulletChart = new BulletChart({ dataSource: chartData, valueField: 'value', targetField: 'target' }); bulletChart.appendTo( '#bullet-chart' ); ``` ### Inject Feature Modules Only When Required A basic Bullet Chart does not require module injection. Inject `BulletTooltip` when tooltips are enabled: ```typescript import { BulletChart, BulletTooltip } from '@syncfusion/ej2-charts'; BulletChart.Inject( BulletTooltip ); ``` Inject `BulletChartLegend` when the range legend is enabled: ```typescript import { BulletChart, BulletChartLegend } from '@syncfusion/ej2-charts'; BulletChart.Inject( BulletChartLegend ); ``` Use: ```typescript BulletChart.Inject(...) ``` Do not use: ```typescript Chart.Inject(...) ``` Do not import an unverified module such as: ```typescript BulletLegend ``` Use: ```typescript BulletChartLegend ``` ### Map Data Explicitly Configure: ```typescript dataSource valueField targetField categoryField ``` Example: ```typescript interface PerformanceData { actual: number; goal: number; metric: string; } const chartData: PerformanceData[] = [ { actual: 55, goal: 75, metric: 'Sales' } ]; const bulletChart: BulletChart = new BulletChart({ dataSource: chartData, valueField: 'actual', targetField: 'goal', categoryField: 'metric' }); bulletChart.appendTo( '#bullet-chart' ); ``` Ensure that actual and target values are finite numbers. ### Configure a Valid Scale ```typescript minimum: 0, maximum: 100, interval: 20 ``` Ensure that: - `minimum` is less than `maximum`. - `interval` is greater than zero. - Actual values are included in the scale. - Target values are included in the scale. - Qualitative range endings are ordered. - The final qualitative range normally includes the maximum. ### Use Either Constructor Target or appendTo Constructor target: ```typescript const bulletChart: BulletChart = new BulletChart( { dataSource: chartData, valueField: 'value', targetField: 'target' }, '#bullet-chart' ); ``` `appendTo` pattern: ```typescript const bulletChart: BulletChart = new BulletChart({ dataSource: chartData, valueField: 'value', targetField: 'target' }); bulletChart.appendTo( '#bullet-chart' ); ``` Do not attach the same instance twice. ### Clean Up Resources When permanently removing the Bullet Chart: - Clear intervals. - Clear polling timeouts. - Remove application-owned listeners. - Close streaming connections. - Revoke object URLs. - Call `bulletChart.destroy()`. ## Quick Start Example ### TypeScript Install the package: ```bash npm install @syncfusion/ej2-charts ``` Add the host: ```html <div id="bullet-chart"></div> ``` Add a stable size: ```css #bullet-chart { width: 100%; min-height: 400px; } ``` Create the Bullet Chart: ```typescript import { BulletChart, BulletTooltip } from '@syncfusion/ej2-charts'; BulletChart.Inject( BulletTooltip ); interface PerformanceData { value: number; target: number; category: string; } const chartData: PerformanceData[] = [ { value: 55, target: 75, category: 'Sales Performance' } ]; const bulletChart: BulletChart = new BulletChart({ title: 'Quarter 1 Performance', subtitle: 'Actual sales compared with target', dataSource: chartData, valueField: 'value', targetField: 'target', categoryField: 'category', minimum: 0, maximum: 100, interval: 20, labelFormat: '{value}%', orientation: 'Horizontal', width: '100%', height: '400px', valueFill: '#0F6CBD', targetColor: '#242424', targetWidth: 6, ranges: [ { end: 50, color: '#D13438', opacity: 0.12, name: 'Below expectations' }, { end: 75, color: '#C19C00', opacity: 0.12, name: 'Approaching target' }, { end: 100, color: '#107C10', opacity: 0.12, name: 'Target achieved' } ], tooltip: { enable: true, template: '<div class="bullet-tooltip">' + '<strong>Actual:</strong> ${value}<br>' + '<strong>Target:</strong> ${target}' + '</div>' }, dataLabel: { enable: true, labelStyle: { color: '#242424', size: '13px', fontWeight: '600' } }, animation: { enable: false } }); bulletChart.appendTo( '#bullet-chart' ); window.addEventListener( 'beforeunload', (): void => { bulletChart.destroy(); } ); ``` Module purpose: - `BulletChart` creates the Bullet Chart component. - `BulletTooltip` enables actual and target tooltips. ### JavaScript with Consolidated CDN Script Use a consistent, pinned EJ2 version in production. ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" > <title> Bullet Chart </title> <script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script> <style> #bullet-chart { width: 100%; min-height: 400px; } .bullet-tooltip { min-width: 130px; padding: 8px 10px; } </style> </head> <body> <div id="bullet-chart"></div> <script> ej.charts.BulletChart.Inject( ej.charts.BulletTooltip ); var chartData = [ { value: 55, target: 75, category: 'Sales Performance' } ]; var bulletChart = new ej.charts.BulletChart({ title: 'Quarter 1 Performance', subtitle: 'Actual sales compared with target', dataSource: chartData, valueField: 'value', targetField: