syncfusion-javascript-circular-gauge

# Implementing Syncfusion Circular Gauge (TypeScript & JavaScript) The Syncfusion Essential JS 2 Circular Gauge visualizes numeric values on a circular scale. It is suitable for dashboards, monitoring systems, KPI displays, progress indicators, speedometers, temperature monitors, and other measurement-oriented applications. This skill covers complete implementations for: - TypeScript applications using npm and module imports. - JavaScript applications using versioned CDN or local global scripts. - Needle, RangeBar, and Marker pointers. - Ranges, axes, labels, ticks, annotations, legends, and tooltips. - Dynamic pointer updates and drag interactions. - Styling, themes, gradients, responsive layouts, accessibility, export, and printing. The Circular Gauge package provides axes, ranges, ticks, labels, pointers, annotations, legends, tooltips, drag interaction, globalization, accessibility, export, and print support. ## Platform Support ### TypeScript Use TypeScript when the application uses: - The `@syncfusion/ej2-circulargauge` npm package. - TypeScript compilation. - Webpack, Vite, or another module bundler. - Strongly typed configuration. - Explicit feature-module injection. - IDE IntelliSense and compile-time validation. Install the package: ```bash npm install @syncfusion/ej2-circulargauge ``` The package uses dependencies such as `@syncfusion/ej2-base`, `@syncfusion/ej2-svg-base`, and `@syncfusion/ej2-pdf-export`. Compatible transitive dependency versions are installed through the package manager. Keep Syncfusion package versions consistent to avoid dependency conflicts. ### JavaScript Use global JavaScript when the application uses: - Versioned CDN scripts. - Locally stored EJ2 global scripts. - Traditional HTML and JavaScript files. - The global `ej` namespace. - No TypeScript compilation or build step. The global Circular Gauge constructor is: ```javascript ej.circulargauge.CircularGauge ``` ### JavaScript Language Level The JavaScript examples use ES5-compatible syntax where practical: ```text var instead of const or let Traditional functions instead of arrow functions No optional chaining No object spread No JavaScript module imports ``` Use TypeScript or modern JavaScript when the application build process transpiles newer syntax. ## When to Use This Skill Use this skill when the task requires: - Creating a basic Circular Gauge. - Building speedometer or meter-style visualizations. - Displaying KPI values. - Creating a progress or completion gauge. - Configuring axis limits, angles, directions, and radii. - Customizing major ticks, minor ticks, and labels. - Adding Needle, RangeBar, or Marker pointers. - Displaying multiple pointers or axes. - Defining normal, warning, and critical ranges. - Adding text, HTML, image, or status annotations. - Enabling pointer and range tooltips. - Showing range legends. - Enabling pointer or range dragging. - Updating pointer values dynamically. - Applying themes, gradients, colors, and fonts. - Supporting responsive layouts. - Supporting RTL languages and localized numbers. - Improving screen-reader and visual accessibility. - Exporting to PNG, JPEG, SVG, or PDF. - Printing the rendered gauge. - Migrating an EJ1 Circular Gauge to EJ2. - Optimizing multiple or frequently updated gauges. ## Implementation Rules ### Rule 1: Use Complete Examples A runnable TypeScript example should include: ```text Imports Feature-module injection Gauge configuration Gauge host element appendTo call Required CSS when applicable ``` A runnable JavaScript example should include: ```text Versioned script references Gauge host element Gauge configuration appendTo call Required CSS when applicable ``` ### Rule 2: Use Explicit DOM Attachment Create the gauge and then call `appendTo`. Preferred TypeScript: ```typescript const gauge: CircularGauge = new CircularGauge({ axes: [{ pointers: [{ value: 65 }] }] }); gauge.appendTo('#gauge'); ``` Preferred JavaScript: ```javascript var gauge = new ej.circulargauge.CircularGauge({ axes: [{ pointers: [{ value: 65 }] }] }); gauge.appendTo('#gauge'); ``` ### Rule 3: Ensure the Host Exists Required HTML: ```html <div id="gauge"></div> ``` Required attachment: ```typescript gauge.appendTo('#gauge'); ``` The host ID and selector must match exactly. ### Rule 4: Inject Every Enabled TypeScript Feature Feature-to-module mapping: ```text Annotations -> Annotations Tooltips -> GaugeTooltip Legend -> Legend Gradients -> Gradient Image export -> ImageExport PDF export -> PdfExport Print -> Print ``` Example: ```typescript import { CircularGauge, Annotations, GaugeTooltip, Legend, Gradient, ImageExport, PdfExport, Print } from '@syncfusion/ej2-circulargauge'; CircularGauge.Inject( Annotations, GaugeTooltip, Legend, Gradient, ImageExport, PdfExport, Print ); ``` Do not inject unused feature modules. ### Rule 5: Keep Imports and Injection Synchronized Every injected module must be imported. Incorrect: ```typescript import { CircularGauge } from '@syncfusion/ej2-circulargauge'; CircularGauge.Inject( Annotations ); ``` Correct: ```typescript import { CircularGauge, Annotations } from '@syncfusion/ej2-circulargauge'; CircularGauge.Inject( Annotations ); ``` ### Rule 6: Keep Values Inside the Axis Range For this axis: ```typescript minimum: 0, maximum: 100 ``` use pointer values such as: ```typescript value: 65 ``` Validate or clamp external values: ```typescript const safeValue: number = Math.min( 100, Math.max(0, requestedValue) ); ``` ### Rule 7: Prefer Public Update Methods Update a pointer with: ```typescript gauge.setPointerValue( axisIndex, pointerIndex, value ); ``` Update an annotation with: ```typescript gauge.setAnnotationValue( axisIndex, annotationIndex, content ); ``` Avoid rebuilding the entire gauge for a simple value update. ### Rule 8: Use Valid Nested Models Needle tail: ```typescript needleTail: { length: '20%', color: '#0066cc' } ``` Cap border: ```typescript cap: { radius: 8, color: '#0066cc', border: { width: 2, color: '#333333' } } ``` Gauge border: ```typescript border: { width: 1, color: '#dddddd' } ``` Tooltip border: ```typescript tooltip: { border: { width: 1, color: '#ffffff' } } ``` ### Rule 9: Use Valid Dragging APIs Gauge-level pointer dragging: ```typescript enablePointerDrag: true ``` Gauge-level range dragging: ```typescript enableRangeDrag: true ``` Use the drag lifecycle: ```text dragStart dragMove dragEnd ``` Do not use: ```typescript allowDragging: true ``` ### Rule 10: Avoid Encoded or Editor-Generated Code Executable HTML must use actual tags: ```html <div id="gauge"></div> ``` Do not use: ```html <div id="gauge"></div> ``` Do not place rich-text editor markup inside code: ```text <a> <strong> <br> data-lexical-text Editor-generated class names ``` ## Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) Use this reference for: - Package installation. - TypeScript project setup. - JavaScript CDN setup. - Local script setup. - Gauge host creation. - Basic axis and pointer configuration. - Module injection. - Development-server guidance. - Initialization troubleshooting. ### Axes Configuration 📄 **Read:** [references/axes-configuration.md](references/axes-configuration.md) Use this reference for: - Axis minimum and maximum. - Start and end angles. - Clockwise and anticlockwise direction. - Axis radius. - Axis-line width, color, and offset. - Axis background. - Major and minor ticks. - Axis labels and formatting. - Ranges. - Multiple axes. - Conditional label rendering. ### Pointers Configuration 📄 **Read:** [references/pointers-configuration.md](references/pointers-configuration.md) Use this reference for: - Needle pointers. - RangeBar pointers. - Marker pointers. - Needle cap and tail customization. - Marker shapes and image markers. - RangeBar rounded corners. - Pointer gradients. - Pointer animations. - Pointer dragging. - Multiple pointers. - Runtime pointer updates. ### Annotations 📄 **Read:** [references/annotations.md](references/annotations.md) Use this reference for: - Annotation module injection. - Plain-text content. - HTML content. - Element-selector templates. - Image annotations. - Annotation positioning. - Text styling. - Multiple annotations. - Dynamic annotation updates. - Annotation render events. - Annotation accessibility. - Annotation export considerations. ### Styling & Appearance 📄 **Read:** [references/styling-appearance.md](references/styling-appearance.md) Use this reference for: - Axis, pointer, range, and tick colors. - Gauge and axis backgrounds. - Borders. - Built-in themes. - Title and label fonts. - Linear and radial gradients. - Gauge positioning. - Responsive dimensions. - Resize handling. - High-contrast presentation. ### Events & Interactions 📄 **Read:** [references/events-interactions.md](references/events-interactions.md) Use this reference for: - Gauge mouse events. - Pointer and range dragging. - Drag start, move, and end. - Pointer, range, and annotation tooltips. - Tooltip templates and styling. - Range legends. - Legend rendering. - Animation completion. - Programmatic pointer updates. - Live-data updates. ### Export & Print 📄 **Read:** [references/export-print.md](references/export-print.md) Use this reference for: - Image export. - PNG, JPEG, and SVG formats. - PDF export. - Portrait and landscape orientation. - Browser printing. - Required export modules. - Export feature-enablement properties. - Export timing. - File-name sanitization. - Annotation export limitations. ### Accessibility & Advanced 📄 **Read:** [references/accessibility-advanced.md](references/accessibility-advanced.md) Use this reference for: - WCAG 2.2 guidance. - Color contrast. - Non-color status communication. - Screen-reader support. - Gauge descriptions. - Dynamic live regions. - Keyboard-accessible external controls. - RTL layout. - Axis direction. - Internationalized labels and tooltips. - EJ1-to-EJ2 migration. - Performance and cleanup practices. ## TypeScript Quick Start ### Required HTML ```html <div id="gauge"></div> ``` ### TypeScript ```typescript import { CircularGauge, Annotations } from '@syncfusion/ej2-circulargauge'; CircularGauge.Inject( Annotations ); const gauge: CircularGauge = new CircularGauge({ width: '100%', height: '450px', title: 'Speed Monitor', axes: [{ minimum: 0, maximum: 120, startAngle: 230, endAngle: 130, radius: '88%', lineStyle: { width: 8, color: '#e0e0e0' }, majorTicks: { interval: 20, width: 2, height: 10, position: 'Inside', color: '#333333' }, minorTicks: { interval: 5, width: 1, height: 5, position: 'Inside', color: '#777777' }, labelStyle: { position: 'Inside', format: '{value}', font: { fontFamily: 'Segoe UI', size: '12px', color: '#333333' } }, ranges: [ { start: 0, end: 40, color: '#107c10', radius: '95%', startWidth: 10, endWidth: 10 }, { start: 40, end: 80, color: '#ffb900', radius: '95%', startWidth: 10, endWidth: 10 }, { start: 80, end: 120, color: '#d13438', radius: '95%', startWidth: 10, endWidth: 10 } ], pointers: [{ value: 65, type: 'Needle', radius: '75%', pointerWidth: 8, color: '#0066cc', cap: { radius: 8, color: '#0066cc', border: { width: 2, color: '#333333' } }, needleTail: { length: '20%', color: '#0066cc' }, animation: { enable: true, duration: 800 } }], annotations: [{ angle: 180, radius: '30%', zIndex: '1', content: '<div style="' + 'font-family:Segoe UI;' +