syncfusion-javascript-linear-gauge

# Implementing Syncfusion EJ2 Linear Gauge in TypeScript and JavaScript The Syncfusion Essential JS 2 Linear Gauge visualizes measurements and metrics on a linear scale. It can display horizontal or vertical scales with axes, ranges, pointers, labels, annotations, tooltips, animations, and interactive pointer dragging. ## When to Use This Skill Use this skill when working with the Syncfusion EJ2 Linear Gauge in pure TypeScript or JavaScript. Typical use cases include: - **Creating a gauge**: Display a scalar value on a linear scale. - **Building measurement interfaces**: Show temperature, pressure, speed, capacity, utilization, or other metrics. - **Configuring axes**: Define minimum and maximum values, tick intervals, labels, and scale direction. - **Adding ranges**: Define colored zones for normal, warning, and critical values. - **Configuring pointers**: Display current, target, average, or threshold values. - **Customizing appearance**: Modify colors, fonts, backgrounds, borders, gradients, and animations. - **Handling interactions**: Respond to mouse, drag, value-change, load, and rendering events. - **Adding annotations**: Place text or trusted HTML content at specific gauge or axis positions. - **Updating values dynamically**: Use `setPointerValue()` for live data and programmatic updates. - **Exporting and printing**: Generate PNG, JPEG, SVG, or PDF output and print the gauge. - **Internationalization**: Apply culture-aware number and currency formatting. - **Accessibility**: Provide meaningful titles, pointer descriptions, visible values, and accessible controls. - **Responsive layouts**: Render gauges inside flexible dashboard, mobile, and fullscreen layouts. - **Migrating from EJ1**: Replace jQuery-based EJ1 Linear Gauge code with the EJ2 object model. ## Documentation and Navigation Guide Choose the reference that matches the task. ### API Reference **Read:** references/api-reference.md Use this reference when you need: - Linear Gauge classes and models - Properties, methods, and events - Axis, range, pointer, tick, label, annotation, and container models - Event argument interfaces - Optional feature modules - Direct API definitions ### Getting Started **Read:** references/getting-started.md Use this reference for: - Installing `@syncfusion/ej2-lineargauge` - Importing `LinearGauge` - Creating the host element - Initializing the first gauge - Understanding the basic configuration structure - Creating TypeScript and global JavaScript applications ### Configuring Axes and Scales **Read:** references/axis-and-scales.md Use this reference for: - Axis minimum and maximum values - Inversed axes - Opposed positioning - Axis-line customization - Major and minor tick marks - Label formatting and positioning - Multiple axes - Dynamic scale updates - Conditional label rendering ### Adding Ranges and Pointers **Read:** references/ranges-and-pointers.md Use this reference for: - Creating and styling ranges - Range positions, offsets, widths, and borders - Linear and radial range gradients - Bar and marker pointers - Image and text pointers - Pointer borders, opacity, and placement - Pointer animations - Drag-enabled pointers - Multiple pointers on one axis - Dynamic pointer and range updates ### Customization and Appearance **Read:** [references/customization-nd-appearance.md Use this reference for: - Gauge-area background, border, and margin - Internal container styling - Normal, RoundedRectangle, and Thermometer containers - Built-in themes - Semantic color schemes - Font and label customization - Dashed axis lines - Range and pointer borders - Solid and gradient backgrounds - Image and text pointers - Conditional labels through `axisLabelRender` - Additional content through annotations ### Interaction and Events **Read:** references/interaction-and-events.md Use this reference for: - `gaugeMouseDown` - `gaugeMouseMove` - `gaugeMouseUp` - `dragStart` - `dragMove` - `dragEnd` - `valueChange` - Draggable pointers - Form integration - Native range and number inputs - Value validation - Snap-to-interval behavior - Real-time updates - API polling - Timer and event cleanup ### Advanced Features **Read:** references/advanced-features.md Use this reference for: - Printing - PNG, JPEG, SVG, and PDF export - Base64 export - Custom export file names - Annotations - Complete-gauge animation - Pointer animation - Reduced-motion handling - Internationalization - Currency and number formatting - Scale-direction considerations - Accessibility - Migrating from Essential JavaScript 1 to EJ2 ### Responsive Design and Dimensions **Read:** references/dimensions-and-responsive.md Use this reference for: - Gauge-level width and height - Internal container dimensions - Percentage-based dimensions - Fixed dimensions - CSS media queries - `ResizeObserver` - Mobile-friendly dimensions - Responsive labels, ticks, ranges, and pointers - Multi-gauge layouts - Fullscreen rendering - Vertical gauges - Resize cleanup ## Required Package Use the pure TypeScript and JavaScript Linear Gauge package. ```bash npm install @syncfusion/ej2-lineargauge ``` Import the Linear Gauge in TypeScript. ```typescript import { LinearGauge } from '@syncfusion/ej2-lineargauge'; ``` For applications using the complete EJ2 global JavaScript bundle, initialize the component through: ```javascript ej.lineargauge.LinearGauge ``` Do not use Angular wrapper packages or Angular component modules in pure TypeScript and JavaScript examples. ```typescript // Do not use in pure TypeScript. import { LinearGaugeModule, LinearGaugeAllModule } from '@syncfusion/ej2-angular-lineargauge'; ``` ## Optional Feature Modules Some Linear Gauge features require module injection in TypeScript. ```typescript import { Annotations, GaugeTooltip, Gradient, ImageExport, LinearGauge, PdfExport, Print } from '@syncfusion/ej2-lineargauge'; LinearGauge.Inject( Annotations, GaugeTooltip, Gradient, ImageExport, PdfExport, Print ); ``` Inject only the modules required by the application. Use the following module mapping: ```text Annotations -> Annotations Tooltips -> GaugeTooltip Gradients -> Gradient Image export -> ImageExport PDF export -> PdfExport Printing -> Print ``` Global JavaScript bundles may already include these features, depending on how the scripts are packaged. ## Quick Start ### index.html ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Syncfusion EJ2 Linear Gauge</title> <style> * { box-sizing: border-box; } body { margin: 0; padding: 24px; background: #f8fafc; color: #111827; font-family: Arial, Helvetica, sans-serif; } main { width: min(100%, 1000px); margin: 0 auto; } h1 { margin: 0 0 8px; font-size: 26px; } .description { margin: 0 0 16px; line-height: 1.5; } .gauge-card { padding: 16px; border: 1px solid #cbd5e1; border-radius: 12px; background: #ffffff; } #gauge-container { display: block; width: 100%; height: 340px; } </style> </head> <body> <main> <h1>System Utilization</h1> <p class="description"> The Linear Gauge shows the current system utilization on a scale from 0 to 100. </p> <section class="gauge-card" aria-label="System utilization gauge" > <div id="gauge-container"></div> </section> </main> </body> </html> ``` ### index.ts ```typescript import { LinearGauge } from '@syncfusion/ej2-lineargauge'; const gauge: LinearGauge = new LinearGauge({ width: '100%', height: '100%', orientation: 'Horizontal', title: 'Current Utilization', titleStyle: { color: '#111827', fontFamily: 'Arial', size: '18px', fontWeight: '700' }, container: { width: 28, height: 0, type: 'RoundedRectangle', backgroundColor: '#e2e8f0', roundedCornerRadius: 8, border: { color: '#94a3b8', width: 1 } }, axes: [ { minimum: 0, maximum: 100, showLastLabel: true, majorTicks: { interval: 20, position: 'Outside', height: 10, width: 2, color: '#334155' }, minorTicks: { interval: 5, position: 'Outside', height: 5, width: 1, color: '#64748b' }, labelStyle: { format: '{value}%', position: 'Outside', offset: 8, font: { fontFamily: 'Arial', size: '13px', color: '#334155', fontWeight: '600' } }, ranges: [ { start: 0, end: 30, color: '#166534', position: 'Inside', startWidth: 15, endWidth: 15 }, { start: 30, end: 70, color: '#854d0e', position: 'Inside', startWidth: 15, endWidth: 15 }, { start: 70, end: 100, color: '#991b1b', position: 'Inside', startWidth: 15, endWidth: 15 } ], pointers: [ { value: 45, type: 'Bar', color: '#1e293b', width: 11, position: 'Cross', roundedCornerRadius: 4, animationDuration: 700, description: 'Current system utilization is 45 percent' } ] } ] }); gauge.appendTo('#gauge-container'); ``` ### index.js ```javascript var gauge = new ej.lineargauge.LinearGauge({ width: '100%', height: '100%', orientation: 'Horizontal', title: 'Current Utilization', titleStyle: { color: '#111827', fontFamily: 'Arial', size: '18px', fontWeight: '700' }, container: { width: 28, height: 0, type: 'RoundedRectangle', backgroundColor: '#e2e8f0', roundedCornerRadius: 8, border: { color: '#94a3b8', width: 1 } }, axes: [ { minimum: 0, maximum: 100, showLastLabel: true, majorTicks: { interval: 20, position: 'Outside', height: 10, width: 2, color: '#334155' }, minorTicks: { interval: 5, position: 'Outside', height: 5, width: 1, color: '#64748b' }, labelStyle: { format: '{value}%', position: 'Outside', offset: 8, font: { fontFamily: 'Arial', size: '13px', color: '#334155', fontWeight: '600' } }, ranges: [ { start: 0, end: 30, color: '#166534', position: 'Inside', startWidth: 15, endWidth: 15 }, { start: 30, end: 70, color: '#854d0e', position: 'Inside', startWidth: 15, endWidth: 15 }, { start: 70, end: 100, color: '#991b1b', position: 'Inside', startWidth: 15, endWidth: 15 } ], pointers: [ { value: 45, type: 'Bar', color: '#1e293b', width: 11, position: 'Cross', roundedCornerRadius: 4, animationDuration: 700, description: 'Current system utilization is 45 percent' } ] } ] }); gauge.appendTo('#gauge-container'); ``` ## Common Patterns ### Pattern 1: Temperature Gauge Use a vertical gauge with a Thermometer container when the data represents temperature. ```typescript import { LinearGauge } from '@syncfusion/ej2-lineargauge'; const currentTemperature: number = 24; const gauge: LinearGauge = new LinearGauge({ width: '100%', height: '500px', orientation: 'Vertical', container: { type: 'Thermometer', width: 30, backgroundColor: '#e2e8f0', border: { color: '#64748b', width: 1 } }, axes: [ { minimum: 0, maximum: 50, majorTicks: { interval: 10, position: 'Outside' }, minorTicks: { interval: 2, position: 'Outside' }, labelStyle: { format: '{value}°C', position: 'Outside' }, ranges: [ { start: 0, end: 15, color: '#2563eb', startWidth: 12, endWidth: 12 }, { start: 15, end: 30, color: '#166534', startWidth: 12, endWidth: 12 }, { start: 30, end: 50, color: '#991b1b', startWidth: 12, endWidth: 12 } ], pointers: [ {