syncfusion-javascript-sparkline

# Implementing Sparklines in Syncfusion TypeScript and JavaScript The Syncfusion EJ2 Sparkline is a lightweight data-visualization component for showing trends, comparisons, proportions, and outcome patterns in a compact area. It is suitable for dashboards, cards, tables, grids, reports, and KPI summaries. This skill covers: - EJ2 TypeScript using `@syncfusion/ej2-charts` - EJ2 JavaScript using `ej.charts.Sparkline` - npm and bundler-based TypeScript applications - Global CDN-based JavaScript applications - Line, Column, Area, Pie, and WinLoss Sparklines - Markers, data labels, tooltips, tracker lines, and range bands - Appearance, axis ranges, accessibility, RTL, and localization - Dynamic property and datasource updates Do not generate Vue, React, Angular, Composition API, directive, provider, or Single File Component examples when this skill is used. ## Platform Support ### TypeScript Use TypeScript when the project requires: - Static type checking - IDE IntelliSense - ES module imports - npm package management - Webpack or another bundler - Typed event arguments - Explicit optional-feature module injection Import the component from: ```typescript import { Sparkline } from '@syncfusion/ej2-charts'; ``` Create and render it: ```typescript const sparkline: Sparkline = new Sparkline(configuration); sparkline.appendTo('#sparkline'); ``` Basic Sparkline features do not require module injection. The following features work without optional module injection: - Basic rendering - Line, Column, Area, Pie, and WinLoss types - Axis ranges and reference line - Markers - Data labels - Range bands - Special-point colors - Appearance customization - Rendering events Tooltip and tracker-line features require `SparklineTooltip`: ```typescript import { Sparkline, SparklineTooltip } from '@syncfusion/ej2-charts'; Sparkline.Inject( SparklineTooltip ); ``` Do not call an empty injection method: ```typescript Sparkline.Inject(); ``` ### JavaScript Use JavaScript when the project requires: - Direct browser execution - CDN-based dependency loading - No TypeScript compilation - No module bundler - Global EJ2 namespace access Create the component through: ```javascript var sparkline = new ej.charts.Sparkline( configuration ); sparkline.appendTo('#sparkline'); ``` When the complete EJ2 global bundle is loaded, explicit TypeScript-style feature injection is generally unnecessary. ## When to Use This Skill Use this skill when the user needs to: - Display compact data trends. - Add a Sparkline to a dashboard card. - Add Sparklines to table or grid cells. - Render a Line, Column, Area, Pie, or WinLoss Sparkline. - Bind a numeric array. - Bind object data through `xName` and `yName`. - Configure Numeric, Category, or DateTime x-values. - Highlight high, low, start, end, or negative points. - Add markers to selected points. - Display data labels. - Enable tooltips. - Enable a tracker line. - Configure one or more range bands. - Set fixed x-axis or y-axis ranges. - Customize the horizontal reference line. - Apply colors, borders, opacity, padding, and themes. - Update the datasource dynamically. - Change the Sparkline type at runtime. - Customize rendered points through events. - Implement accessible text and data alternatives. - Enable right-to-left rendering. - Localize surrounding labels, summaries, numbers, or dates. ## Validation Workflow Before generating Sparkline code, validate the following items. ### Step 1: Identify the Platform Determine whether the user needs: - TypeScript - JavaScript - Both TypeScript and JavaScript Do not substitute a framework-specific wrapper. ### Step 2: Identify the Sparkline Type Supported values are: ```text Line Column Area Pie WinLoss ``` Configure the type at Sparkline root level: ```typescript type: 'Line' ``` ### Step 3: Identify the Datasource Structure A datasource can be: - A numeric array - An object array with numeric x-values - An object array with category x-values - An object array with DateTime x-values Numeric array: ```typescript dataSource: [ 2, 6, 4, 1, 3 ] ``` Object array: ```typescript dataSource: [ { month: 'Jan', sales: 35 }, { month: 'Feb', sales: 28 } ], xName: 'month', yName: 'sales' ``` Do not provide `xName` or `yName` for a plain numeric array. ### Step 4: Validate valueType Use: ```typescript valueType: 'Numeric' ``` for numeric x-values. Use: ```typescript valueType: 'Category' ``` for string x-values. Use: ```typescript valueType: 'DateTime' ``` for JavaScript `Date` values. Do not use: ```typescript valueType: 'Double' ``` ### Step 5: Identify Optional Features | Feature | TypeScript module | |---|---| | Basic rendering | No optional module | | Sparkline types | No optional module | | Markers | No optional module | | Data labels | No optional module | | Axis configuration | No optional module | | Range bands | No optional module | | Appearance | No optional module | | Tooltip | `SparklineTooltip` | | Tracker line | `SparklineTooltip` | ### Step 6: Validate Configuration Hierarchy Use: ```typescript markerSettings ``` for markers. Use: ```typescript dataLabelSettings ``` for data labels. Use: ```typescript tooltipSettings ``` for tooltips. Use: ```typescript tooltipSettings: { trackLineSettings: { visible: true } } ``` for the tracker line. Use: ```typescript rangeBandSettings: [ { startRange: 30, endRange: 40 } ] ``` for range bands. Use: ```typescript axisSettings: { lineSettings: { visible: true } } ``` for the horizontal reference line. ### Step 7: Validate the Host Confirm that: - The host element exists. - The selector matches the host ID. - The parent has an available width. - The Sparkline has a usable height. - The EJ2 theme stylesheet is loaded. - A component initialized in a hidden parent is refreshed after becoming visible. ## Navigation Guide ### Getting Started Read: ```text references/getting-started.md ``` Use it for: - Package installation - TypeScript setup - JavaScript setup - CDN usage - Container setup - Initial rendering - Numeric, Category, and DateTime binding - Dynamic datasource updates ### Sparkline Types Read: ```text references/sparkline-types.md ``` Use it for: - Line Sparkline - Column Sparkline - Area Sparkline - Pie Sparkline - WinLoss Sparkline - Type-specific appearance - Runtime type switching - Type-selection guidance ### Appearance and Styling Read: ```text references/appearance-styling.md ``` Use it for: - Sparkline fill - Line width - Series border - Container background - Container border - Internal padding - Pie palette - Special-point colors - Responsive sizing - Themes - Runtime styling updates ### Markers and Special Points Read: ```text references/markers-and-points.md ``` Use it for: - All-point markers - Start and end markers - High and low markers - Negative-point markers - Marker fill - Marker border - Marker opacity - Marker size - Special-point colors - Marker-rendering events ### Data Labels and Tooltips Read: ```text references/data-labels-and-tooltips.md ``` Use it for: - Data-label visibility - Data-label formatting - Data-label appearance - Tooltip module injection - Tooltip visibility - Tooltip formatting - Tooltip templates - Tracker-line configuration - Dynamic interaction updates ### Range Bands Read: ```text references/range-bands.md ``` Use it for: - Single range bands - Multiple range bands - Target intervals - Performance zones - Tolerance bands - Range-band color and opacity - Axis-range alignment - Runtime band updates ### Axis Customization Read: ```text references/axis-customization.md ``` Use it for: - `minX` - `maxX` - `minY` - `maxY` - Horizontal reference-line value - Reference-line appearance - Fixed comparison scales - Dynamic range calculation Sparkline does not expose conventional x-axis and y-axis labels, tick labels, label rotation, or an axis-label style model. ### User Interaction Read: ```text references/user-interaction.md ``` Use it for: - Tooltips - Tracker lines - Tooltip templates - Point-rendering events - Marker-rendering events - Data-label-rendering events - Load and loaded events - Custom application-managed selection - Accessible interaction alternatives ### Accessibility and Localization Read: ```text references/accessibility-localization.md ``` Use it for: - Text alternatives - Color contrast - Non-color visual cues - Data-table alternatives - Dynamic update announcements - Native keyboard controls - RTL rendering - Localized categories - Locale-aware number and date formatting ## Installation Install the EJ2 Charts package: ```bash npm install @syncfusion/ej2-charts ``` The required transitive dependencies are installed automatically. Do not require separate installation of `ej2-base`, `ej2-data`, or `ej2-svg-base` unless the package manager reports a specific resolution problem. ## Theme Setup Configure the corresponding component theme when required: ```typescript theme: 'Material' ``` ## Host Setup ```html <div class="sparkline-wrapper"> <div id="sparkline"></div> </div> ``` ```css .sparkline-wrapper { width: 100%; max-width: 500px; } #sparkline { width: 100%; height: 140px; } ``` Render only after the host element exists: ```typescript const host: HTMLElement | null = document.querySelector( '#sparkline' ); if (!host) { throw new Error( 'The Sparkline host element was not found.' ); } sparkline.appendTo(host); ``` ## Quick Start ### TypeScript #### 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>EJ2 TypeScript Sparkline</title> <style> .sparkline-wrapper { width: 100%; max-width: 400px; } #sparkline { width: 100%; height: 120px; } </style> </head> <body> <div class="sparkline-wrapper"> <div id="sparkline"></div> </div> <script scr="index.js"></script> </body> </html> ``` #### index.ts ```typescript import { Sparkline } from '@syncfusion/ej2-charts'; interface PopulationData { year: string; population: number; } const populationData: PopulationData[] = [ { year: '2005', population: 20090440 }, { year: '2006', population: 20264080 }, { year: '2007', population: 20434180 }, { year: '2008', population: 21007310 }, { year: '2009', population: 21262640 }, { year: '2010', population: 21515750 }, { year: '2011', population: 21766710 } ]; const sparkline: Sparkline = new Sparkline({ width: '100%', height: '120px', type: 'Line', valueType: 'Category', dataSource: populationData, xName: 'year', yName: 'population', fill: '#2563EB', lineWidth: 2, markerSettings: { visible: [ 'High', 'Low' ], size: 7, fill: '#FFFFFF', border: { color: '#1D4ED8', width: 2 } } }); sparkline.appendTo('#sparkline'); ``` ### JavaScript ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" > <title>EJ2 JavaScript Sparkline</title> <script src="https://cdn.syncfusion.com/ej2/34.2.2/dist/ej2.min.js"></script> <style> .sparkline-wrapper { width: 100%; max-width: 400px; } #sparkline { width: 100%; height: 120px; } </style> </head> <body> <div class="sparkline-wrapper">