Syncfusion React Linear Gauge

Implementing Syncfusion React Linear Gauge

When to Use This Skill

Use the Linear Gauge component when you need to:

• Display measurements on a linear/horizontal scale (temperature gauges, thermometers, fuel indicators)
• Monitor real-time data with animated pointer updates (sensor readings, system metrics)
• Show progress or percentages in a linear format
• Create dashboards with multiple gauges displaying KPIs
• Visualize ranges with different colors (e.g., safe, warning, critical zones)
• Build responsive data visualizations with customizable appearance and interactivity
• Print or export gauge visualizations for reports and documentation

The Linear Gauge is ideal for applications requiring visual representation of values on a horizontal/linear scale with customizable axes, pointers, ranges, and interactive features.

---

Component Overview

Syncfusion React Linear Gauge (@syncfusion/ej2-react-lineargauge) is a data visualization component that displays values on a linear scale. It consists of:

• Axes - The linear scale with customizable range, ticks, labels, and styling
• Pointers - Value indicators in two types: Bar (default) or Marker (shapes)
• Ranges - Colored segments representing value ranges (e.g., cold, warm, hot)
• Annotations - Text or image overlays for labels and callouts
• Ticks & Labels - Scale markers with customizable formatting
• Export - Print, PDF, PNG, or SVG export capabilities

---

Documentation and Navigation Guide

Choose the reference based on what you need to implement:

Getting Started & Setup

📄 Read: references/getting-started.md

• Install @syncfusion/ej2-react-lineargauge package
• Setup in Vite or Create React App
• Basic component initialization
• Minimal working example
• CSS imports and themes
• When to read: First time setup or new project integration

Gauge Structure: Axes, Ticks & Labels

📄 Read: references/axis-ticks-labels.md

• Configure axes (minimum, maximum range)
• Customize axis line (height, width, color)
• Configure major and minor ticks
• Format and customize labels
• Set label units and formatting
• Multiple axes configuration
• When to read: Building the core gauge structure and scale

Pointer Types & Configuration

📄 Read: references/pointers.md

• Bar pointer type (default, fill styles)
• Marker pointer types (Circle, Rectangle, Triangle, Diamond, Image, Text)
• Setting and updating pointer values
• Customize pointer appearance (width, color, radius)
• Multiple pointers on same axis
• Drag-drop interactions
• Performance optimization
• When to read: Adding value indicators and interactive features

Ranges & Annotations

📄 Read: references/ranges-annotations.md

• Creating ranges with start/end values
• Range styling (colors, gradient effects)
• Range labels and positions
• Text annotations for callouts and labels
• Image annotations
• Positioning and alignment
• When to read: Highlighting value zones or adding descriptive elements

Visual Appearance & Customization

📄 Read: references/appearance-customization.md

• Add titles
• Set gauge dimensions (width, height, margin)
• Customize background and borders
• Apply themes and color schemes
• Responsive design patterns
• CSS class customization
• RTL language support
• When to read: Styling and customizing gauge appearance

Advanced Features

📄 Read: references/advanced-features.md

• Animation effects and timing
• Event handling (valueChange, print, export)
• Tooltips and hover effects
• Print and export to PDF/PNG/SVG
• Real-time data binding and updates
• Combining multiple features
• Performance tips and optimization
• When to read: Adding interactions, animations, or export functionality

Quick Start Example

Here's a minimal working example to get started:

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';
import '@syncfusion/ej2-lineargauge/styles/material.css';

export function App() {
  return (
    <div style={{ height: '400px', width: '100%' }}>
      <LinearGaugeComponent 
        title="Temperature Monitor"
        orientation="Horizontal"
      >
        <AxesDirective>
          <AxisDirective 
            minimum={0}
            maximum={100}
            labelStyle={{ format: '{value}°C' }}
          >
            <RangesDirective>
              <RangeDirective start={0} end={30} color='#1E90FF' />
              <RangeDirective start={30} end={70} color='#FFA500' />
              <RangeDirective start={70} end={100} color='#FF4500' />
            </RangesDirective>
            
            <PointersDirective>
              <PointerDirective value={55} />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </LinearGaugeComponent>
    </div>
  );
}

Install the package first:

npm install @syncfusion/ej2-react-lineargauge --save

---

Common Patterns

Pattern 1: Simple Temperature Gauge

<LinearGaugeComponent title="Temperature">
  <AxesDirective>
    <AxisDirective minimum={-40} maximum={50} labelStyle={{ format: '{value}°C' }}>
      <RangesDirective>
        <RangeDirective start={-40} end={0} color='#4CAF50' />
        <RangeDirective start={0} end={25} color='#8BC34A' />
        <RangeDirective start={25} end={50} color='#FF5722' />
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={20} />
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

Pattern 2: Progress/Percentage Indicator

<PointersDirective>
  <PointerDirective 
    value={75} 
    type='Marker'
    markerType='Rectangle'
    width={20}
    color='#007AFF'
  />
</PointersDirective>

Pattern 3: Real-Time Updates

const [value, setValue] = useState(50);

useEffect(() => {
  const timer = setInterval(() => {
    setValue(prev => (prev + (Math.random() - 0.5) * 10) % 100);
  }, 1000);
  return () => clearInterval(timer);
}, []);

<PointerDirective value={value} />

---

LinearGaugeComponent API Reference

Verified Props (Based on Official Syncfusion Documentation)

---

AxisDirective API Reference

Verified Props for AxisDirective

labelStyle Format Options

• { format: '{value}' } - Shows value as-is
• { format: '{value}°C' } - Adds °C suffix
• { format: '${value}K' } - Adds $ prefix and K suffix
• { format: '{value}%' } - Adds % suffix

⚠️ NOT SUPPORTED:

• ❌ majorTicksInterval - Not a valid property
• ❌ minorTicksInterval - Not a valid property
• ❌ axisLineStyle - Not a valid property (use axis-level styling instead)

---

PointerDirective API Reference

Verified Props for PointerDirective

Pointer Type Examples

Bar Pointer (Default)

<PointerDirective value={140} color='blue' width={8} />

Marker Pointer

<PointerDirective 
  value={75} 
  type='Marker'
  markerType='Rectangle'
  width={15}
  color='#1976D2'
/>

---

RangeDirective API Reference

Verified Props for RangeDirective

Example with Width

<RangeDirective start={0} end={80} color='#4CAF50' startWidth={15} endWidth={15} />

---

Working Code Examples

Example 1: Temperature Gauge (Verified)

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={200} labelStyle={{ format: '{value}°C' }}>
          <PointersDirective>
            <PointerDirective value={140} color='green'></PointerDirective>
          </PointersDirective>
          <RangesDirective>
            <RangeDirective start={0} end={80} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={80} end={120} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={120} end={140} startWidth={15} endWidth={15}></RangeDirective>
            <RangeDirective start={140} end={200} startWidth={15} endWidth={15}></RangeDirective>
          </RangesDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

Example 2: Progress Indicator (Verified)

<LinearGaugeComponent title="Project Status">
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100} labelStyle={{ format: '{value}%' }}>
      <RangesDirective>
        <RangeDirective start={0} end={30} color='#EF5350' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={30} end={70} color='#FFCA28' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={70} end={100} color='#66BB6A' startWidth={15} endWidth={15}></RangeDirective>
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={75} color='#1976D2' width={8}></PointerDirective>
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

Example 3: Multi-Pointer Gauge (Verified)

<LinearGaugeComponent>
  <AxesDirective>
    <AxisDirective minimum={0} maximum={1000} labelStyle={{ format: '${value}K' }}>
      <RangesDirective>
        <RangeDirective start={0} end={400} color='#E53935' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={400} end={700} color='#FB8C00' startWidth={15} endWidth={15}></RangeDirective>
        <RangeDirective start={700} end={1000} color='#43A047' startWidth={15} endWidth={15}></RangeDirective>
      </RangesDirective>
      <PointersDirective>
        <PointerDirective value={650} color='#1976D2' width={6}></PointerDirective>
        <PointerDirective value={850} type='Marker' markerType='Circle' width={10} color='#FF6F00'></PointerDirective>
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

---

LinearGaugeComponent Methods & Events

Use the following methods/events when you need interactivity like animation lifecycle, tooltips, drag, export, and print:

Methods

• destroy()
• export(type, fileName, orientation?, allowDownload?)
• print(id?)
• setAnnotationValue(annotationIndex, content, axisValue?)
• setPointerValue(axisIndex, pointerIndex, value)

Events

• load, loaded, resized
• valueChange (pointer value changes)
• dragStart, dragMove, dragEnd
• beforePrint
• tooltipRender
• animationComplete
• annotationRender, axisLabelRender
• gaugeMouseDown, gaugeMouseMove, gaugeMouseUp, gaugeMouseLeave

---

Common Use Cases

1. Temperature Monitoring - Real-time temperature with hot/cold indicators 2. Sensor Data Visualization - Display sensor readings (pressure, humidity, etc.) 3. Performance Metrics - Show system performance, CPU usage, memory 4. Progress Indicators - Visualize task completion or download progress 5. Fuel/Battery Level - Monitor resource consumption 6. Speed/RPM Gauges - Display rotation speeds or velocities 7. Network Traffic - Show bandwidth usage in real-time 8. Quality/Score Indicators - Display ratings or quality metrics

---

Next Steps

1. Start with Getting Started to install and setup your first gauge 2. Build structure using Axes, Ticks & Labels reference 3. Add pointers using Pointer Types & Configuration reference 4. Highlight zones with Ranges & Annotations reference 5. Customize appearance with Visual Appearance reference 6. Add interactions with Advanced Features reference 7. Test accessibility using Accessibility reference

For more details or advanced scenarios, consult the specific reference files linked above.

Advanced Features in React Linear Gauge

See API Reference: API Reference

Table of Contents

• Animations
• Animate Pointer Value
• Animate Gauge Load
• Event Handling
• Value Change Event
• Drag Events
• Gauge Mouse Events
• Load / Resize / Animation Complete
• Rendering Hooks
• Print Event
• Tooltips
• Basic Tooltip
• Tooltip Customization
• Custom Tooltip Template
• Print and Export
• Print
• Export
• Real-Time Data Binding
• Polling Example
• Performance Optimization
• Memoize Display Components
• useCallback for Event Handlers
• Debounce Rapid Updates
• Combining Multiple Features
• Comprehensive Example

Animations

Use animationDuration on pointers (and the initial load animation) to smooth value transitions.

Animate Pointer Value

import React, { useState } from 'react';
import {
  LinearGaugeComponent,
  AxesDirective,
  AxisDirective,
  PointersDirective,
  PointerDirective
} from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [value, setValue] = useState(40);

  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective
              value={value}
              animationDuration={1000}
            />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

Animate Gauge Load

<LinearGaugeComponent animationDuration={1500}>
  {/* AxesDirective + pointers/ranges */}
</LinearGaugeComponent>

Event Handling

React Linear Gauge supports lifecycle and interaction events from LinearGaugeComponent.

Value Change Event

Triggers while changing the value of the pointer by UI interaction.

import React, { useState } from 'react';
import {
  LinearGaugeComponent,
  AxesDirective,
  AxisDirective,
  PointersDirective,
  PointerDirective
} from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [value, setValue] = useState(50);

  const handleValueChange = (e) => {
    console.log('Pointer value changed:', e.value);
    setValue(e.value);
  };

  return (
    <LinearGaugeComponent valueChange={handleValueChange}>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective value={value} enableDrag={true} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

Drag Events

<LinearGaugeComponent
  dragStart={() => console.log('dragStart')}
  dragMove={() => console.log('dragMove')}
  dragEnd={() => console.log('dragEnd')}
>
  {/* AxesDirective */}
</LinearGaugeComponent>

Gauge Mouse Events

<LinearGaugeComponent
  gaugeMouseDown={() => console.log('gaugeMouseDown')}
  gaugeMouseMove={() => console.log('gaugeMouseMove')}
  gaugeMouseUp={() => console.log('gaugeMouseUp')}
  gaugeMouseLeave={() => console.log('gaugeMouseLeave')}
>
  {/* AxesDirective */}
</LinearGaugeComponent>

Load / Resize / Animation Complete

<LinearGaugeComponent
  load={() => console.log('load')}
  loaded={() => console.log('loaded')}
  resized={() => console.log('resized')}
  animationComplete={() => console.log('animationComplete')}
>
  {/* AxesDirective */}
</LinearGaugeComponent>

Rendering Hooks

Use these to customize or cancel rendering for annotations, axis labels, and tooltip content.

<LinearGaugeComponent
  annotationRender={(args) => {
    // inspect args, then set/modify args.content if needed
  }}
  axisLabelRender={(args) => {
    // example: hide some labels
    if (args.value % 20 === 0) args.cancel = true;
  }}
  tooltipRender={(args) => {
    // inspect args before tooltip renders
  }}
>
  {/* AxesDirective */}
</LinearGaugeComponent>

Print Event

<LinearGaugeComponent beforePrint={() => console.log('beforePrint')}>
  {/* AxesDirective */}
</LinearGaugeComponent>

Tooltips

Configure tooltip via the tooltip prop on LinearGaugeComponent.

Basic Tooltip

<LinearGaugeComponent
  tooltip={{
    enable: true,
    format: '{value}°C'
  }}
>
<Inject services={[GaugeTooltip]} />
</LinearGaugeComponent>

Tooltip Customization (style + formatting)

<LinearGaugeComponent
  tooltip={{
    enable: true,
    fill: '#FFFFFF',
    format: '{value}',
    border: { width: 1, color: '#CCCCCC' },
    textStyle: {
      fontFamily: 'Arial',
      size: '12px',
      color: '#333333'
    }
  }}
>
  <Inject services={[GaugeTooltip]} />
  {/* AxesDirective */}
</LinearGaugeComponent>

Custom Tooltip Template

const tooltipTemplate = (args) => {
  return `<div>
    <strong>${args.value}</strong><br/>
    <small>Custom tooltip</small>
  </div>`;
};

<LinearGaugeComponent
  tooltip={{
    enable: true,
    template: tooltipTemplate
  }}
>
  <Inject services={[GaugeTooltip]} />
  {/* AxesDirective */}
</LinearGaugeComponent>

Print and Export

Use component ref to call print() and export().

Print

import React, { useRef } from 'react';
import { LinearGaugeComponent } from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const gaugeRef = useRef(null);

  return (
    <div>
      <button onClick={() => gaugeRef.current?.print()}>Print</button>
      <LinearGaugeComponent ref={gaugeRef}>
        {/* AxesDirective */}
      </LinearGaugeComponent>
    </div>
  );
}

Export

gaugeRef.current?.export('PDF', 'gauge.pdf', false, true);
gaugeRef.current?.export('PNG', 'gauge.png', false, true);
gaugeRef.current?.export('SVG', 'gauge.svg', false, true);

Real-Time Data Binding

Update pointer values from live data by updating React state.

Polling Example

import React, { useEffect, useState } from 'react';
import {
  LinearGaugeComponent,
  AxesDirective,
  AxisDirective,
  PointersDirective,
  PointerDirective
} from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [value, setValue] = useState(50);

  useEffect(() => {
    const interval = setInterval(async () => {
      // Replace with your API call
      const response = await fetch('/api/sensor-data');
      const data = await response.json();
      setValue(data.value);
    }, 2000);

    return () => clearInterval(interval);
  }, []);

  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective value={value} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

Performance Optimization

Memoize Display Components

import React, { memo } from 'react';

const GaugeDisplay = memo(({ value, title }) => (
  <LinearGaugeComponent title={title}>
    {/* AxesDirective */}
  </LinearGaugeComponent>
));

export default GaugeDisplay;

useCallback for Event Handlers

const handleValueChange = React.useCallback((e) => {
  console.log(e.value);
}, []);

<LinearGaugeComponent valueChange={handleValueChange}>
  {/* AxesDirective */}
</LinearGaugeComponent>

Debounce Rapid Updates

// Debounce on your state updates so the pointer doesn't re-render too frequently

Combining Multiple Features

Comprehensive Example

import React, { useState, useRef, useEffect, useCallback } from 'react';
import {
  LinearGaugeComponent,
  AxesDirective,
  AxisDirective,
  RangesDirective,
  RangeDirective,
  PointersDirective,
  PointerDirective,
  AnnotationsDirective,
  AnnotationDirective
} from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const gaugeRef = useRef(null);
  const [value, setValue] = useState(50);

  useEffect(() => {
    const interval = setInterval(() => {
      setValue((prev) => {
        const newVal = prev + (Math.random() - 0.5) * 30;
        return Math.max(0, Math.min(100, newVal));
      });
    }, 2000);

    return () => clearInterval(interval);
  }, []);

  const handleValueChange = useCallback((e) => {
    console.log('Manual pointer adjustment:', e.value);
    setValue(e.value);
  }, []);

  return (
    <div style={{ padding: '20px' }}>
      <div style={{ marginBottom: '10px' }}>
        <button onClick={() => gaugeRef.current?.export('PDF', 'gauge.pdf', false, true)}>
          Export as PDF
        </button>
      </div>

      <LinearGaugeComponent
        ref={gaugeRef}
        title="Temperature Monitor"
        valueChange={handleValueChange}
        tooltip={{ enable: true, format: '{value}°C' }}
        height="400px"
      >
        <AxesDirective>
          <AxisDirective minimum={0} maximum={100} labelStyle={{ format: '{value}°C' }}>
            <RangesDirective>
              <RangeDirective start={0} end={33} color="#4CAF50" />
              <RangeDirective start={33} end={66} color="#FFC107" />
              <RangeDirective start={66} end={100} color="#F44336" />
            </RangesDirective>

            <PointersDirective>
              <PointerDirective value={value} enableDrag={true} animationDuration={800} />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>

        <AnnotationsDirective>
          <AnnotationDirective
            content={`<div style='font-weight: bold; font-size: 18px;'>${Math.round(value)}°C</div>`}
            x={50}
            y={50}
          />
        </AnnotationsDirective>
      </LinearGaugeComponent>
    </div>
  );
}

export default App;

Linear Gauge API Reference (React)

This file summarizes the main API surface of the Syncfusion React LinearGauge component for quick reference. For full docs see: https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default

Component

LinearGaugeComponent (from @syncfusion/ej2-react-lineargauge)

Key Properties (selected)

• allowImageExport (boolean)
• allowPdfExport (boolean)
• allowPrint (boolean)
• animationDuration (number)
• annotations (AnnotationModel[]) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/annotationmodel
• axes (AxisModel[]) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/axismodel
• background (string)
• border (BorderModel) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/bordermodel
• container (ContainerModel) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/containermodel
• description (string)
• edgeLabelPlacement (string)
• enablePersistence (boolean)
• enableRtl (boolean)
• format (string)
• height (string)
• margin (MarginModel) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/marginmodel
• orientation (string)
• rangePalettes (string[][])
• theme (string)
• title (string)
• titleStyle (FontModel) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/fontmodel
• tooltip (TooltipSettingsModel) — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/tooltipsettingsmodel
• useGroupingSeparator (boolean)
• width (string)

Methods

• destroy(): void — destroy the widget — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default#destroy
• export(type, fileName, orientation, allowDownload): Promise — export image/PDF — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default#export
• print(id?: string | string[] | Element): void — print the gauge — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default#print
• setAnnotationValue(annotationIndex, content, axisValue): void — update annotation — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default#setannotationvalue
• setPointerValue(axisIndex, pointerIndex, value): void — set pointer value programmatically — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default#setpointervalue

Events

• animationComplete — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/ianimationcompleteeventargs
• annotationRender — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/iannotationrendereventargs
• axisLabelRender — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/iaxislabelrendereventargs
• beforePrint — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/iprinteventargs
• dragEnd, dragMove, dragStart — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/ipointerdrageventargs
• gaugeMouseDown, gaugeMouseLeave, gaugeMouseMove, gaugeMouseUp — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/imouseeventargs
• load — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/iloadeventargs
• loaded — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/iloadedeventargs
• resized — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/iresizeeventargs
• tooltipRender — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/itooltiprendereventargs
• valueChange — https://ej2.syncfusion.com/react/documentation/api/linear-gauge/ivaluechangeeventargs

Child directives

• AnnotationsDirective > AnnotationDirective
• RangesDirective > RangeDirective
• PointersDirective > PointerDirective

Short usage example

<LinearGaugeComponent
  allowImageExport
  allowPdfExport
  allowPrint
  animationDuration={1500}
  axes={[{ minimum: 0, maximum: 100 }]}
  annotations={[{ axisIndex:0, axisValue:50, content:'<div>50</div>' }]}
  annotationRender={handleAnnotationRender}
  axisLabelRender={handleAxisLabelRender}
/>

Notes

• Configure ranges, pointers and annotations using the corresponding directives.
• Use enableDrag on pointers to allow user interactions; handle valueChange to sync state.
• Themes supported (material, bootstrap, fluent, tailwind, etc.) — use the global CSS/theme package.

For complete type definitions, refer to the Syncfusion API docs: https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default

Visual Appearance & Customization in React Linear Gauge

See API Reference: API Reference

Table of Contents

• Title
• Title Styling
• Gauge Dimensions
• Using Container Div
• Using Component Props
• Margin and Padding
• Responsive Sizing
• Background and Border
• Basic Background
• Border Styling
• Advanced Background
• Shadow Effect
• Themes and Color Schemes
• Material Theme
• Bootstrap Theme
• Bootstrap 5 Theme
• Fabric Theme
• Tailwind CSS Theme
• High Contrast Theme
• Responsive Design
• Mobile-First Layout
• Container Queries
• Media Queries
• CSS Class Customization
• Using CSS Modules
• Using Inline Styles
• RTL Support
• Enable RTL
• RTL in HTML
• Dynamic RTL Toggle
• Common Customization Patterns
• Pattern 1: Modern Dashboard Gauge
• Pattern 2: Minimal/Clean Design
• Pattern 3: Dark Mode
• Troubleshooting
• Next Steps

Title

Add meaningful headings to your gauge:

import React from 'react';
import { LinearGaugeComponent } from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent 
      title="Linear Gauge"
    >
      {/* axes, pointers, ranges */}
    </LinearGaugeComponent>
  );
}

export default App;

Title Styling

<LinearGaugeComponent 
  title="Temperature Monitor"
  titleStyle={{
    fontFamily: 'Arial',
    fontStyle: 'italic',
    fontWeight: 'bold',
    size: '18px',
    color: '#1976D2'
  }}
>
  {/* configuration */}
</LinearGaugeComponent>

Title Style Properties:

• fontFamily - Font name
• fontStyle - 'normal', 'italic', 'oblique'
• fontWeight - 'normal', 'bold', or numeric (100-900)
• size - Font size
• color - Text color (hex, rgb, or name)

Gauge Dimensions

Control the size of the gauge container:

Using Container Div

<div style={{ height: '400px', width: '100%' }}>
  <LinearGaugeComponent>
    {/* configuration */}
  </LinearGaugeComponent>
</div>

Using Component Props

<LinearGaugeComponent
  width="100%"
  height="400px"
>
  {/* configuration */}
</LinearGaugeComponent>

Margin and Padding

<LinearGaugeComponent
  width="100%"
  height="500px"
  margin={{
    left: 20,
    right: 20,
    top: 20,
    bottom: 20
  }}
>
  {/* configuration */}
</LinearGaugeComponent>

Responsive Sizing

<div style={{ 
  height: '100vh',      // Full viewport height
  width: '100%'         // Full width
}}>
  <LinearGaugeComponent>
    {/* configuration */}
  </LinearGaugeComponent>
</div>

Background and Border

Customize the gauge background and border:

Basic Background

<LinearGaugeComponent
  background="#FFFFFF"
>
  {/* configuration */}
</LinearGaugeComponent>

Border Styling

<LinearGaugeComponent
  border={{
    color: '#D3D3D3',   // Border color
    width: 2            // Border width
  }}
>
  {/* configuration */}
</LinearGaugeComponent>

Advanced Background

<LinearGaugeComponent
  background="linear-gradient(to bottom, #f5f5f5, #ffffff)"
  border={{
    color: '#1976D2',
    width: 2
  }}
>
  {/* configuration */}
</LinearGaugeComponent>

Shadow Effect

<div style={{
  padding: '10px',
  boxShadow: '0 4px 8px rgba(0, 0, 0, 0.1)',
  borderRadius: '4px'
}}>
  <LinearGaugeComponent>
    {/* configuration */}
  </LinearGaugeComponent>
</div>

Themes and Color Schemes

Syncfusion provides built-in themes. Import the appropriate theme CSS:

Material Theme

import '@syncfusion/ej2-lineargauge/styles/material.css';

Bootstrap Theme

import '@syncfusion/ej2-lineargauge/styles/bootstrap.css';

Bootstrap 5 Theme

import '@syncfusion/ej2-lineargauge/styles/bootstrap5.css';

Fabric Theme

import '@syncfusion/ej2-lineargauge/styles/fabric.css';

Tailwind CSS Theme

import '@syncfusion/ej2-lineargauge/styles/tailwind.css';

High Contrast Theme

import '@syncfusion/ej2-lineargauge/styles/highcontrast.css';

Responsive Design

Mobile-First Layout

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
         PointersDirective, PointerDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [orientation, setOrientation] = React.useState('Horizontal');

  React.useEffect(() => {
    // Detect screen size
    const handleResize = () => {
      if (window.innerWidth < 600) {
        setOrientation('Vertical');
      } else {
        setOrientation('Horizontal');
      }
    };

    handleResize();
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return (
    <div style={{ 
      width: '100%', 
      height: '100vh',
      padding: '10px',
      boxSizing: 'border-box'
    }}>
      <LinearGaugeComponent orientation={orientation}>
        {/* axes, pointers */}
      </LinearGaugeComponent>
    </div>
  );
}

export default App;

Container Queries (Modern CSS)

<div style={{
  containerType: 'size',
  width: '100%',
  height: '100vh'
}}>
  <LinearGaugeComponent width="100%" height="100%">
    {/* configuration */}
  </LinearGaugeComponent>
</div>

Media Queries

export function App() {
  const [width, setWidth] = React.useState('600px');
  const [height, setHeight] = React.useState('400px');

  React.useEffect(() => {
    const mediaQuery = window.matchMedia('(max-width: 768px)');
    
    const handleChange = (e) => {
      if (e.matches) {
        setWidth('100%');
        setHeight('500px');
      } else {
        setWidth('600px');
        setHeight('400px');
      }
    };

    mediaQuery.addListener(handleChange);
    handleChange(mediaQuery);
    
    return () => mediaQuery.removeListener(handleChange);
  }, []);

  return (
    <LinearGaugeComponent width={width} height={height}>
      {/* configuration */}
    </LinearGaugeComponent>
  );
}

CSS Class Customization

Using CSS Modules

// GaugeCustom.module.css
.gaugeContainer {
  background: linear-gradient(to bottom, #f0f0f0, #ffffff);
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  padding: 20px;
}

.gaugeTitle {
  color: #1976D2;
  font-weight: bold;
}

// App.tsx
import styles from './GaugeCustom.module.css';
import { LinearGaugeComponent } from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <div className={styles.gaugeContainer}>
      <LinearGaugeComponent title="My Gauge">
        {/* configuration */}
      </LinearGaugeComponent>
    </div>
  );
}

Using Inline Styles

const gaugeStyle = {
  container: {
    background: '#f9f9f9',
    borderRadius: '8px',
    padding: '20px',
    boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)'
  },
  title: {
    color: '#1976D2',
    fontWeight: 'bold',
    marginBottom: '10px'
  }
};

export function App() {
  return (
    <div style={gaugeStyle.container}>
      <h2 style={gaugeStyle.title}>System Monitor</h2>
      <LinearGaugeComponent>
        {/* configuration */}
      </LinearGaugeComponent>
    </div>
  );
}

RTL Support

Support right-to-left languages like Arabic and Hebrew:

Enable RTL

<LinearGaugeComponent enableRtl={true}>
  {/* configuration */}
</LinearGaugeComponent>

RTL in HTML

<html dir="rtl">
  <body>
    <div id="root"></div>
  </body>
</html>

Dynamic RTL Toggle

import React, { useState } from 'react';
import { LinearGaugeComponent } from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [rtl, setRtl] = useState(false);

  return (
    <div>
      <button onClick={() => setRtl(!rtl)}>
        {rtl ? 'English (LTR)' : 'العربية (RTL)'}
      </button>
      
      <LinearGaugeComponent enableRtl={rtl}>
        {/* configuration */}
      </LinearGaugeComponent>
    </div>
  );
}

Common Customization Patterns

Pattern 1: Modern Dashboard Gauge

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
         RangesDirective, RangeDirective, PointersDirective, PointerDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <div style={{
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      padding: '20px',
      borderRadius: '12px',
      color: 'white'
    }}>
      <LinearGaugeComponent
        title="CPU Usage"
        background='rgba(255, 255, 255, 0.95)'
        border={{ color: '#E0E0E0', width: 1 }}
        width="100%"
        height="300px"
      >
        <AxesDirective>
          <AxisDirective minimum={0} maximum={100} labelStyle={{ format: '{value}%' }}>
            <RangesDirective>
              <RangeDirective start={0} end={50} color='#4CAF50' />
              <RangeDirective start={50} end={75} color='#FFC107' />
              <RangeDirective start={75} end={100} color='#F44336' />
            </RangesDirective>
            <PointersDirective>
              <PointerDirective value={65} />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </LinearGaugeComponent>
    </div>
  );
}

Pattern 2: Minimal/Clean Design

<LinearGaugeComponent
  title="Minimal Gauge"
  background="transparent"
  border={{ color: 'transparent' }}
  titleStyle={{ color: '#333' }}
  margin={{ top: 0, bottom: 0, left: 0, right: 0 }}
>
  {/* axes, pointers */}
</LinearGaugeComponent>

Pattern 3: Dark Mode

<LinearGaugeComponent
  background="#1E1E1E"
  border={{ color: '#333333', width: 1 }}
  titleStyle={{ color: '#FFFFFF' }}
>
  <AxesDirective>
    <AxisDirective 
      line={{ color: '#666666' }}
    >
      {/* ranges, pointers */}
    </AxisDirective>
  </AxesDirective>
</LinearGaugeComponent>

Troubleshooting

Q: Gauge not taking full width

• Set width="100%" on component or parent div
• Verify parent container has explicit width

Q: Title/labels cut off

• Increase height of gauge
• Adjust margin to provide more space

Q: Theme not applying

• Verify CSS import is at top of file
• Check for conflicting global styles
• Clear browser cache

Q: RTL text not rendering

• Set enableRtl={true} on component
• Set dir="rtl" on HTML element
• Use appropriate font family for language

Next Steps

• Read Advanced Features for animations and interactions
• Read Accessibility for inclusive design practices
• Read Internationalization for multi-language support

Axis, Ticks & Labels in React Linear Gauge

See API Reference: API Reference

Table of Contents

• Axis Range
• Setting Minimum and Maximum
• Line Customization
• Example: Custom Colored Line
• Ticks Configuration
• Major Ticks
• Minor Ticks
• Both Together
• Label Customization
• Basic Label Styling
• Common Label Formats
• Label Position and Offset
• Example: Temperature Labels
• Multiple Axes
• Axis Orientation
• Vertical (Default)
• Horizontal
• Dynamic Orientation
• Common Patterns
• Pattern 1: Temperature with Semantic Ranges
• Pattern 2: Percentage with Decimal Labels
• Pattern 3: Compact Axis with Minimal Ticks
• Troubleshooting
• Next Steps

Axis Range

The axis defines the scale range for the Linear Gauge using minimum and maximum properties. These values determine the start and end points displayed on the gauge.

Setting Minimum and Maximum

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective 
          minimum={20} 
          maximum={200}
        >
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Key Props:

• minimum - Start value of the axis (default: 0)
• maximum - End value of the axis (default: 100)

Use Cases:

• Temperature gauge: minimum={-50} maximum={50}
• Percentage: minimum={0} maximum={100}
• Speed: minimum={0} maximum={200}

Line Customization

The axis line is the baseline of the gauge. Customize its appearance using the line property object:

<AxisDirective 
  minimum={0} 
  maximum={100}
  line={{
    height: 150,        // Length of the axis line in pixels
    width: 2,           // Thickness of the axis line
    color: '#4286f4',   // Line color (hex, rgb, or name)
    offset: 2           // Distance from the gauge container edge
  }}
>
</AxisDirective>

Line Properties:

• height - Length of the axis line (number in pixels)
• width - Thickness of the axis line (number in pixels, default: 1)
• color - Color of the line (default: '#000000')
• offset - Offset from the container edge (default: 0)

Example: Custom Colored Line

<AxisDirective 
  line={{
    height: 200,
    width: 3,
    color: '#FF6B6B',
    offset: 10
  }}
>
</AxisDirective>

Ticks Configuration

Ticks are interval markers on the axis. There are two types:

• Major ticks - Larger marks at primary intervals
• Minor ticks - Smaller marks at secondary intervals

Major Ticks

<AxisDirective 
  minimum={0}
  maximum={100}
  majorTicks={{
    interval: 20,      // Spacing between major ticks
    height: 15,        // Length of each tick
    width: 2,          // Thickness of each tick
    color: '#000000'   // Color of ticks
  }}
>
</AxisDirective>

Minor Ticks

Minor ticks appear between major ticks:

<AxisDirective 
  minimum={0}
  maximum={100}
  minorTicks={{
    interval: 5,       // Spacing between minor ticks
    height: 8,         // Length of each tick
    width: 1,          // Thickness of each tick
    color: '#999999'   // Color of ticks
  }}
>
</AxisDirective>

Both Together

<AxisDirective 
  minimum={20}
  maximum={140}
  majorTicks={{ interval: 20, height: 15, color: '#333333' }}
  minorTicks={{ interval: 5, height: 8, color: '#CCCCCC' }}
>
</AxisDirective>

Label Customization

Labels are the numeric values displayed along the axis. Customize their appearance and format:

Basic Label Styling

<AxisDirective 
  minimum={0}
  maximum={100}
  labelStyle={{
    format: '{value}%',           // Format with placeholder
    font: {
      size: '12px',               // Font size
      color: '#333333',          // Text color
      fontFamily: 'Arial'
    }
  }}
>
</AxisDirective>

Common Label Formats

// Percentage
labelStyle={{ format: '{value}%' }}

// Temperature with unit
labelStyle={{ format: '{value}°C' }}

// Decimal places
labelStyle={{ format: '{value:.2f}' }}

// Currency
labelStyle={{ format: '${value}' }}

// Custom text
labelStyle={{ format: 'Value: {value}' }}

Label Position and Offset

<AxisDirective 
  labelStyle={{
    position: 'Outside',   // 'Inside' or 'Outside'
    offset: 10,            // Distance from axis line
    format: '{value}°C'
  }}
>
</AxisDirective>

Example: Temperature Labels

<AxisDirective 
  minimum={-50}
  maximum={50}
  labelStyle={{
    format: '{value}°C',
    font: {
      size: '14px',
      color: '#FF5722',
      fontFamily: 'Georgia',
      fontStyle: 'italic'
    }
  }}
  majorTicks={{ interval: 10 }}
  minorTicks={{ interval: 5 }}
>
</AxisDirective>

Multiple Axes

A single gauge can have multiple axes stacked vertically. This is useful for comparing related measurements:

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent 
      title="Multiple Axes Example"
      height="500px"
    >
      <AxesDirective>
        {/* First Axis - Temperature */}
        <AxisDirective 
          minimum={0}
          maximum={100}
          labelStyle={{ format: '{value}°C' }}
          line={{ height: 150, offset: 20 }}
        >
          <PointersDirective>
            <PointerDirective value={45} />
          </PointersDirective>
        </AxisDirective>

        {/* Second Axis - Humidity */}
        <AxisDirective 
          minimum={0}
          maximum={100}
          labelStyle={{ format: '{value}%' }}
          line={{ height: 150, offset: 100 }}
        >
          <PointersDirective>
            <PointerDirective value={65} />
          </PointersDirective>
        </AxisDirective>

        {/* Third Axis - Pressure */}
        <AxisDirective 
          minimum={950}
          maximum={1050}
          labelStyle={{ format: '{value}mb' }}
          line={{ height: 150, offset: 180 }}
        >
          <PointersDirective>
            <PointerDirective value={1013} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Key Points:

• Use line.offset to position each axis vertically
• Each axis can have different ranges, labels, and pointers
• Ideal for comparing multiple metrics in one view

Axis Orientation

The Linear Gauge can be rendered in two orientations:

Vertical (Default)

<LinearGaugeComponent orientation="Vertical">
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100} />
  </AxesDirective>
</LinearGaugeComponent>

Horizontal

<LinearGaugeComponent orientation="Horizontal">
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100} />
  </AxesDirective>
</LinearGaugeComponent>

Dynamic Orientation

Choose based on container or user preference:

const [orientation, setOrientation] = React.useState('Horizontal');

<LinearGaugeComponent orientation={orientation}>
  {/* axes */}
</LinearGaugeComponent>

<button onClick={() => setOrientation('Vertical')}>
  Switch to Vertical
</button>

Common Patterns

Pattern 1: Temperature with Semantic Ranges

<AxisDirective 
  minimum={-40}
  maximum={50}
  labelStyle={{
    format: '{value}°C',
    font: { size: '12px' }
  }}
  majorTicks={{ interval: 10 }}
  minorTicks={{ interval: 2 }}
  line={{ height: 200, width: 2, color: '#1976D2' }}
>
</AxisDirective>

Pattern 2: Percentage with Decimal Labels

<AxisDirective 
  minimum={0}
  maximum={100}
  labelStyle={{ 
    format: '{value:.1f}%',
    font: { size: '11px' }
  }}
  majorTicks={{ interval: 25 }}
  minorTicks={{ interval: 5 }}
>
</AxisDirective>

Pattern 3: Compact Axis with Minimal Ticks

<AxisDirective 
  minimum={0}
  maximum={1000}
  labelStyle={{ format: '{value}ms' }}
  majorTicks={{ interval: 200 }}
  line={{ height: 100 }}
>
</AxisDirective>

Troubleshooting

Q: Labels are overlapping

• Reduce font size: size: '10px'
• Use fewer major ticks: interval: 25 instead of 10
• Increase axis height: line: { height: 250 }

Q: Ticks not showing

• Verify interval is smaller than range (0-100 with interval 50 only shows 2 ticks)
• Ensure height > 0

Q: Format not applying

• Use {value} as placeholder in format string
• Test with simple format first: '{value}'

Next Steps

• Read Pointer Types to add and customize pointers
• Read Ranges & Annotations to highlight value zones
• Read Customization for advanced styling options

Getting Started with React Linear Gauge

See API Reference: API Reference

Table of Contents

• Installation
• Project Setup
• Setup with Vite (Recommended)
• Setup with Create React App
• Basic Component Import
• CSS Themes
• Minimal Working Example
• First Gauge with Custom Axis Range
• Adding Ranges for Visual Zones
• Adding a Title
• Setting Container Dimensions
• Running Your Application
• Next Steps

Installation

The Linear Gauge component is provided through the @syncfusion/ej2-react-lineargauge package. Install it using npm:

npm install @syncfusion/ej2-react-lineargauge --save

This will also automatically install the required dependencies:

• @syncfusion/ej2-lineargauge - Core Linear Gauge library
• @syncfusion/ej2-base - Base utilities
• @syncfusion/ej2-svg-base - SVG rendering engine
• @syncfusion/ej2-react-base - React integration

Project Setup

Setup with Vite (Recommended)

Vite provides faster development with optimized builds:

npm create vite@latest my-app -- --template react-ts
cd my-app
npm run dev

Then install the Linear Gauge package:

npm install @syncfusion/ej2-react-lineargauge --save

Setup with Create React App

If using Create React App instead:

npx create-react-app my-app
cd my-app
npm install @syncfusion/ej2-react-lineargauge --save

Basic Component Import

To use the Linear Gauge, import the required components from the Syncfusion package:

import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

CSS Themes

Import the appropriate theme CSS file. Syncfusion provides several built-in themes:

// Material theme (light)
import '@syncfusion/ej2-lineargauge/styles/material.css';

// Or Bootstrap theme
import '@syncfusion/ej2-lineargauge/styles/bootstrap.css';

// Or Fabric theme
import '@syncfusion/ej2-lineargauge/styles/fabric.css';

// Or Tailwind CSS theme
import '@syncfusion/ej2-lineargauge/styles/tailwind.css';

Place the theme import at the top of your App.tsx or main.tsx file.

Minimal Working Example

Here's the simplest way to get a Linear Gauge running:

import React from 'react';
import { LinearGaugeComponent } from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return <LinearGaugeComponent></LinearGaugeComponent>;
}

export default App;

This renders a basic gauge with default settings (0-100 scale, single bar pointer at value 50).

First Gauge with Custom Axis Range

To set a custom axis range and pointer value:

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={200}>
          <PointersDirective>
            <PointerDirective value={140} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

This creates a gauge with:

• Axis range: 0 to 200
• Pointer value: 140

Adding Ranges for Visual Zones

Ranges highlight different value zones with colors:

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective, RangesDirective, RangeDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent title="Temperature Gauge">
      <AxesDirective>
        <AxisDirective 
          minimum={0} 
          maximum={100}
          labelStyle={{ format: '{value}°C' }}
        >
          <RangesDirective>
            <RangeDirective start={0} end={30} color='#1E90FF' />
            <RangeDirective start={30} end={70} color='#FFA500' />
            <RangeDirective start={70} end={100} color='#FF4500' />
          </RangesDirective>
          
          <PointersDirective>
            <PointerDirective value={55} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

This creates:

• Temperature scale from 0-100°C
• Three colored zones: cold (blue), warm (orange), hot (red-orange)
• Pointer at 55°C in the warm zone

Adding a Title

Display a meaningful heading for your gauge:

<LinearGaugeComponent 
  title="Linear Gauge" 
>
  {/* axes, pointers, ranges */}
</LinearGaugeComponent>

Setting Container Dimensions

Control the size of the gauge container:

<div style={{ height: '400px', width: '100%' }}>
  <LinearGaugeComponent>
    {/* configuration */}
  </LinearGaugeComponent>
</div>

Or set dimensions directly on the component:

<LinearGaugeComponent
  width="100%"
  height="400px"
>
  {/* configuration */}
</LinearGaugeComponent>

Running Your Application

Start the development server:

npm run dev

Open your browser and navigate to the local URL (typically http://localhost:5173 for Vite or http://localhost:3000 for Create React App).

Next Steps

• Read Axis, Ticks & Labels reference to customize the scale
• Read Pointer Types reference to use different pointer visualizations
• Read Ranges & Annotations reference to add descriptive elements
• Read Customization reference for styling and appearance

Pointer Types & Configuration in React Linear Gauge

See API Reference: API Reference

Table of Contents

• Bar Pointer Type
• Basic Bar Pointer
• Customized Bar Pointer
• Bar Gradient Fill
• Marker Pointer Type
• Basic Marker Pointer
• Available Marker Shapes
• Customized Marker Pointer
• Image Marker
• Text Marker
• Setting Pointer Values
• Static Value
• Dynamic Value with State
• Real-Time Updates
• Pointer Customization
• Styling Properties
• Animation
• Multiple Pointers
• Drag and Drop
• Handling Drag Events
• Performance Tips
• 1. Use Bar Pointers for Simple Cases
• 2. Limit Animation Duration
• 3. Use useCallback for Event Handlers
• 4. Debounce Frequent Updates
• Troubleshooting
• Next Steps

Bar Pointer Type

Bar pointers fill the gauge from the minimum to the pointer value. This is the default pointer type.

Basic Bar Pointer

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective 
              value={65}
              type="Bar"
            />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Result: A bar that fills from 0 to 65 on the scale.

Customized Bar Pointer

<PointerDirective 
  value={65}
  type="Bar"
  width={15}              // Thickness of the bar
  color="#FF6B6B"         // Bar color
  offset={5}              // Distance from axis line
  roundedCornerRadius={0}
/>

Bar Properties:

• type - Must be "Bar"
• value - Current value (0-100 by default)
• width - Bar thickness in pixels (default: 7)
• color - Bar color (hex, rgb, or name)
• offset - Distance from axis line
• roundedCornerRadius - Rounded corner radius

Bar Gradient Fill

<PointerDirective 
  value={75}
  type="Bar"
  color="url(#barGradient)"
  width={20}
/>

Marker Pointer Type

Marker pointers use a shape instead of a bar. They're useful for precise value indication.

Basic Marker Pointer

<PointerDirective 
  value={80}
  type="Marker"
  markerType="Circle"
/>

Result: A circular marker at value 80.

Available Marker Shapes

The markerType property supports these shapes:

// Circle marker
<PointerDirective value={50} type="Marker" markerType="Circle" />

// Rectangle marker
<PointerDirective value={50} type="Marker" markerType="Rectangle" />

// Triangle marker
<PointerDirective value={50} type="Marker" markerType="Triangle" />

// Inverted Triangle marker (default)
<PointerDirective value={50} type="Marker" markerType="InvertedTriangle" />

// Diamond marker
<PointerDirective value={50} type="Marker" markerType="Diamond" />

Customized Marker Pointer

<PointerDirective 
  value={60}
  type="Marker"
  markerType="Rectangle"
  width={20}              // Marker width
  color="#00BCD4"         // Marker color
  border={{
    width: 2,
    color: "#1976D2"      // Border color
  }}
  offset={0}              // Distance from axis line
/>

Image Marker

Use a custom image as a marker:

<PointerDirective 
  value={50}
  type="Marker"
  markerType="Image"
  imageUrl="/path/to/marker.png"
  width={30}
  height={30}
/>

Note: imageUrl must be a valid image path (PNG, JPG, SVG).

Text Marker

Display text as a marker:

<PointerDirective 
  value={75}
  type="Marker"
  markerType="Text"
  text="75%"
/>

Setting Pointer Values

Static Value

<PointerDirective value={50} />

Dynamic Value with State

import React, { useState } from 'react';

export function App() {
  const [value, setValue] = useState(50);

  return (
    <div>
      <button onClick={() => setValue(value + 10)}>Increase</button>
      <button onClick={() => setValue(value - 10)}>Decrease</button>
      
      <LinearGaugeComponent>
        <AxesDirective>
          <AxisDirective minimum={0} maximum={100}>
            <PointersDirective>
              <PointerDirective value={value} />
            </PointersDirective>
          </AxisDirective>
        </AxesDirective>
      </LinearGaugeComponent>
    </div>
  );
}

Real-Time Updates

import React, { useState, useEffect } from 'react';

export function App() {
  const [value, setValue] = useState(50);

  useEffect(() => {
    // Update every second with random variation
    const interval = setInterval(() => {
      setValue(prev => {
        const newValue = prev + (Math.random() - 0.5) * 20;
        return Math.max(0, Math.min(100, newValue)); // Clamp between 0-100
      });
    }, 1000);
    
    return () => clearInterval(interval);
  }, []);

  return (
    <LinearGaugeComponent>
      {/* Configuration with value={value} */}
    </LinearGaugeComponent>
  );
}

Pointer Customization

Styling Properties

<PointerDirective 
  value={70}
  type="Bar"
  width={15}
  color="#FF6B6B"
  opacity={0.8}          // Transparency (0-1)
  offset={3}             // Distance from axis
  border={{
    width: 2,
    color: "#C1192B"
  }}
  roundedCornerRadius={2}       // For bar pointers only
/>

Animation

<PointerDirective 
  value={75}
  animationDuration={1000}  // 1 second animation
/>

Multiple Pointers

Add multiple pointers to compare or track multiple values:

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective, 
         PointersDirective, PointerDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent title="Multi-Pointer Gauge">
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            {/* Actual value */}
            <PointerDirective 
              value={65}
              type="Bar"
              color="#1976D2"
              width={12}
            />
            
            {/* Target value */}
            <PointerDirective 
              value={80}
              type="Marker"
              markerType="Circle"
              color="#FF6B6B"
              width={20}
            />
            
            {/* Previous value */}
            <PointerDirective 
              value={55}
              type="Marker"
              markerType="Diamond"
              color="#FFA500"
              width={15}
            />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Use Cases:

• Actual vs Target: Compare current value against goal
• Current vs Previous: Track changes over time
• Multiple Sensors: Display readings from different sources

Drag and Drop

Enable users to drag pointers to update values interactively:

<PointerDirective 
  value={50}
  type="Bar"
  enableDrag={true}
/>

Handling Drag Events

import React, { useState } from 'react';

export function App() {
  const [value, setValue] = useState(50);

  const onPointerValueChange = (e) => {
    // e.value contains the new pointer value
    console.log('Pointer moved to:', e.value);
    setValue(e.value);
  };

  return (
    <LinearGaugeComponent
      valueChange={onPointerValueChange}
    >
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective 
              value={value}
              type="Bar"
              enableDrag={true}
            />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

Performance Tips

1. Use Bar Pointers for Simple Cases

Bar pointers render faster than marker pointers with animations.

// Fast
<PointerDirective value={50} type="Bar" />

// Slower with many animations
<PointerDirective value={50} type="Marker" markerType="Circle" 
  animationDuration={2000} />

2. Limit Animation Duration

Keep animations under 1-2 seconds for responsive feel:

// Good
<PointerDirective value={50} animationDuration={800} />

// Slow
<PointerDirective value={50} animationDuration={5000} />

3. Use useCallback for Event Handlers

Prevent unnecessary re-renders:

import React, { useCallback } from 'react';

export function App() {
  const handlePointerChange = useCallback((e) => {
    // Update pointer value
  }, []);

  return (
    <LinearGaugeComponent valueChange={handlePointerChange}>
      {/* */}
    </LinearGaugeComponent>
  );
}

4. Debounce Frequent Updates

For real-time data, debounce updates to avoid excessive re-renders:

import React, { useState, useEffect } from 'react';

export function App() {
  const [value, setValue] = useState(50);
  const [displayValue, setDisplayValue] = useState(50);

  useEffect(() => {
    // Update display every 500ms instead of on every change
    const timer = setTimeout(() => {
      setDisplayValue(value);
    }, 500);
    return () => clearTimeout(timer);
  }, [value]);

  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective value={displayValue} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

Troubleshooting

Q: Pointer value not updating

• Ensure value prop is bound to state: value={stateValue}
• Check that axis minimum and maximum encompass the pointer value

Q: Animation not playing

• Verify animationDuration > 0
• Check that component is not already at the final value

Q: Marker not visible

• Ensure markerType is valid (Circle, Rectangle, Triangle, etc.)
• Check width is not 0
• Verify color contrasts with background

Next Steps

• Read Ranges & Annotations to add value zone highlights
• Read Advanced Features for event handling and animations
• Read Customization for styling options

Ranges & Annotations in React Linear Gauge

Table of Contents

• Creating Ranges
• Basic Range Example
• Range Properties
• Range Styling
• Solid Colors
• Semantic Colors (Traffic Light)
• Gradient Colors
• Tapered Ranges (Varying Width)
• Temperature Gauge Styling
• Range Labels
• Text Annotations
• Basic Text Annotation
• Position Annotations
• HTML Content in Annotations
• Image Annotations
• Annotation Positioning
• Positioning System
• Common Positions
• Common Patterns
• Pattern 1: Temperature Gauge with Zones and Labels
• Pattern 2: Dashboard Gauge with Status Indicator
• Pattern 3: Multiple Annotations
• Pattern 4: Ranges for CPU Usage
• Interactive Annotations with State
• API Reference
• Troubleshooting
• Next Steps

Creating Ranges

Ranges are colored segments on the gauge that represent different value zones. They help visualize which range a value falls into.

Basic Range Example

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
         RangesDirective, RangeDirective, PointersDirective, PointerDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <RangesDirective>
            <RangeDirective start={0} end={33} color='#1E90FF' />
            <RangeDirective start={33} end={66} color='#FFA500' />
            <RangeDirective start={66} end={100} color='#FF6B6B' />
          </RangesDirective>
          
          <PointersDirective>
            <PointerDirective value={45} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Result: Three colored zones - blue (low), orange (medium), red (high).

Range Properties

<RangeDirective 
  start={30}           // Start value of the range
  end={70}             // End value of the range
  color="#FF6B6B"      // Range color
  startWidth={15}      // Width at start (optional)
  endWidth={15}        // Width at end (optional)
/>

Key Props:

• start - Range start value (required)
• end - Range end value (required)
• color - Range color (hex, rgb, or name)
• startWidth - Width at start of range (pixels)
• endWidth - Width at end of range (pixels)

Range Styling

Solid Colors

<RangeDirective start={0} end={30} color='#1E90FF' />      // Blue
<RangeDirective start={30} end={70} color='#FFA500' />     // Orange
<RangeDirective start={70} end={100} color='#FF6B6B' />    // Red

Semantic Colors (Traffic Light)

<RangesDirective>
  <RangeDirective start={0} end={33} color='#4CAF50' />    {/* Green - Good */}
  <RangeDirective start={33} end={66} color='#FFC107' />   {/* Yellow - Warning */}
  <RangeDirective start={66} end={100} color='#F44336' />  {/* Red - Critical */}
</RangesDirective>

Gradient Colors

Use CSS gradients for smooth color transitions:

<RangeDirective 
  start={0} 
  end={50}
  color="url(#rangeGradient)"
/>

Tapered Ranges (Varying Width)

<RangeDirective 
  start={20}
  end={80}
  startWidth={25}      // Thicker at start
  endWidth={5}         // Thinner at end (tapered effect)
  color='#FF6B6B'
/>

Temperature Gauge Styling

<RangesDirective>
  {/* Freezing */}
  <RangeDirective start={-50} end={0} color='#0066CC' startWidth={15} endWidth={15} />
  
  {/* Cold */}
  <RangeDirective start={0} end={10} color='#1E90FF' startWidth={15} endWidth={15} />
  
  {/* Cool */}
  <RangeDirective start={10} end={20} color='#00CED1' startWidth={15} endWidth={15} />
  
  {/* Comfortable */}
  <RangeDirective start={20} end={28} color='#228B22' startWidth={15} endWidth={15} />
  
  {/* Warm */}
  <RangeDirective start={28} end={35} color='#FFA500' startWidth={15} endWidth={15} />
  
  {/* Hot */}
  <RangeDirective start={35} end={50} color='#FF4500' startWidth={15} endWidth={15} />
</RangesDirective>

Range Labels

Syncfusion Linear Gauge ranges are primarily styled using start/end and color (and optional border/gradient). If you need text labels for ranges, use AnnotationDirective to place text at a specific axis position.

<AnnotationsDirective>
  {/* Label placed near the middle of the range (axisValue) */}
  <AnnotationDirective
    content="<div style='color:#1E90FF; font-weight:bold;'>Low</div>"
    axisIndex={0}
    axisValue={16.5}
    zIndex="1"
  />
</AnnotationsDirective>

Text Annotations

Annotations are text elements placed at specific positions. They're useful for labels and callouts.

Basic Text Annotation

import React from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
         AnnotationsDirective, AnnotationDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  return (
    <LinearGaugeComponent>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
        </AxisDirective>
      </AxesDirective>
      
      <AnnotationsDirective>
        <AnnotationDirective 
          content="<div>Current: 65%</div>"
          x={50}
          y={100}
        />
      </AnnotationsDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Position Annotations

<AnnotationDirective 
  content="<div style='color: #1976D2; font-weight: bold;'>Temperature: 25°C</div>"
  x={45}          // X position (% or px)
  y={50}          // Y position (% or px)
  zIndex={'1'}      // Stacking order
/>

HTML Content in Annotations

<AnnotationDirective 
  content={`
    <div style='
      padding: 8px 12px;
      background: white;
      border: 1px solid #ccc;
      border-radius: 4px;
      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
    '>
      <strong>Value: 65%</strong><br/>
      <small>Target: 75%</small>
    </div>
  `}
  x={50}
  y={80}
/>

Image Annotations

Use images for visual markers or icons:

<AnnotationDirective 
  content="<img src='/images/thermometer.svg' width='30' height='30' />"
  x={50}
  y={20}
/>

Annotation Positioning

Positioning System

• x - Horizontal position (0-100% or pixels)
• y - Vertical position (0-100% or pixels)
• zIndex - Stacking order (higher = on top)

Common Positions

{/* Top center */}
<AnnotationDirective content="..." x={50} y={10} />

{/* Center */}
<AnnotationDirective content="..." x={50} y={50} />

{/* Bottom center */}
<AnnotationDirective content="..." x={50} y={90} />

{/* Left side */}
<AnnotationDirective content="..." x={10} y={50} />

{/* Right side */}
<AnnotationDirective content="..." x={90} y={50} />

Common Patterns

Pattern 1: Temperature Gauge with Zones and Labels

import React, { useState } from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
         RangesDirective, RangeDirective, PointersDirective, PointerDirective,
         AnnotationsDirective, AnnotationDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [temp, setTemp] = useState(22);

  return (
    <LinearGaugeComponent title="Room Temperature">
      <AxesDirective>
        <AxisDirective 
          minimum={0}
          maximum={40}
          labelStyle={{ format: '{value}°C' }}
        >
          <RangesDirective>
            <RangeDirective start={0} end={15} color='#4CAF50' />
            <RangeDirective start={15} end={25} color='#8BC34A' />
            <RangeDirective start={25} end={40} color='#FF5722' />
          </RangesDirective>
          
          <PointersDirective>
            <PointerDirective value={temp} type="Bar" />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
      
      <AnnotationsDirective>
        <AnnotationDirective 
          content={`<div style='font-size: 16px; font-weight: bold;'>${temp}°C</div>`}
          x={50}
          y={75}
        />
      </AnnotationsDirective>
    </LinearGaugeComponent>
  );
}

export default App;

Pattern 2: Dashboard Gauge with Status Indicator

<LinearGaugeComponent title="System Performance">
  <AxesDirective>
    <AxisDirective minimum={0} maximum={100} labelStyle={{ format: '{value}%' }}>
      <RangesDirective>
        <RangeDirective start={0} end={30} color='#FF6B6B' />
        <RangeDirective start={30} end={70} color='#FFA500' />
        <RangeDirective start={70} end={100} color='#4CAF50' />
      </RangesDirective>
      
      <PointersDirective>
        <PointerDirective value={85} type="Bar" />
      </PointersDirective>
    </AxisDirective>
  </AxesDirective>
  
  <AnnotationsDirective>
    <AnnotationDirective 
      content="<div style='color: #4CAF50; font-weight: bold;'>✓ OPTIMAL</div>"
      x={50}
      y={80}
    />
  </AnnotationsDirective>
</LinearGaugeComponent>

Pattern 3: Multiple Annotations

<AnnotationsDirective>
  {/* Current value label */}
  <AnnotationDirective 
    content="<div style='font-size: 18px; font-weight: bold;'>65%</div>"
    x={50}
    y={40}
  />
  
  {/* Zone indicator */}
  <AnnotationDirective 
    content="<div style='font-size: 12px; color: #666;'>NORMAL ZONE</div>"
    x={50}
    y={60}
  />
  
  {/* Timestamp */}
  <AnnotationDirective 
    content="<div style='font-size: 10px; color: #999;'>Updated: 14:32:15</div>"
    x={50}
    y={90}
  />
</AnnotationsDirective>

Pattern 4: Ranges for CPU Usage

<RangesDirective>
  {/* Normal */}
  <RangeDirective start={0} end={50} color='#4CAF50' startWidth={20} endWidth={20} />
  
  {/* Warning */}
  <RangeDirective start={50} end={80} color='#FFC107' startWidth={20} endWidth={20} />
  
  {/* Critical */}
  <RangeDirective start={80} end={100} color='#FF5722' startWidth={20} endWidth={20} />
</RangesDirective>

Interactive Annotations with State

Update annotations based on pointer value:

import React, { useState } from 'react';
import { LinearGaugeComponent, AxesDirective, AxisDirective,
         PointersDirective, PointerDirective, AnnotationsDirective, AnnotationDirective } 
  from '@syncfusion/ej2-react-lineargauge';

export function App() {
  const [value, setValue] = useState(50);
  
  const getStatus = (val) => {
    if (val < 33) return { status: 'LOW', color: '#4CAF50' };
    if (val < 66) return { status: 'MEDIUM', color: '#FFA500' };
    return { status: 'HIGH', color: '#FF6B6B' };
  };

  const status = getStatus(value);

  return (
    <LinearGaugeComponent valueChange={(e) => setValue(e.value)}>
      <AxesDirective>
        <AxisDirective minimum={0} maximum={100}>
          <PointersDirective>
            <PointerDirective value={value} enableDrag={true} />
          </PointersDirective>
        </AxisDirective>
      </AxesDirective>
      
      <AnnotationsDirective>
        <AnnotationDirective 
          content={`<div style='color: ${status.color}; font-weight: bold;'>${status.status}</div>`}
          x={50}
          y={75}
        />
      </AnnotationsDirective>
    </LinearGaugeComponent>
  );
}

API Reference

Key Properties (selected)

• allowImageExport (boolean) — enable image export
• allowPdfExport (boolean)
• allowPrint (boolean)
• animationDuration (number)
• annotations (AnnotationModel[])
• axes (AxisModel[])
• background (string)
• border (BorderModel)
• container (ContainerModel)
• description (string)
• edgeLabelPlacement (string)
• enablePersistence (boolean)
• enableRtl (boolean)
• format (string)
• height (string)
• margin (MarginModel)
• orientation (string)
• rangePalettes (string[][])
• theme (string)
• title (string)
• tooltip (TooltipSettingsModel)
• useGroupingSeparator (boolean)
• width (string)

Methods

• destroy(): void
• export(type, fileName, orientation, allowDownload): Promise
• print(id?: string | string[] | Element): void
• setAnnotationValue(annotationIndex, content, axisValue): void
• setPointerValue(axisIndex, pointerIndex, value): void

Events

• animationComplete — fired after animation completes
• annotationRender — fired before an annotation is rendered
• axisLabelRender — fired while rendering axis labels
• beforePrint — fired before print
• dragEnd, dragMove, dragStart — pointer drag lifecycle
• gaugeMouseDown, gaugeMouseLeave, gaugeMouseMove, gaugeMouseUp — mouse interactions
• load, loaded — component load lifecycle
• resized — when gauge is resized
• tooltipRender — before tooltip is shown
• valueChange — when pointer value changes

Example (short)

<LinearGaugeComponent
  allowImageExport
  allowPdfExport
  allowPrint
  animationDuration={1500}
  axes={[{ minimum:0, maximum:100 }]}
  annotations={[{ axisIndex:0, axisValue:50, content:'<div>50</div>' }]}
  annotationRender={handleAnnotationRender}
  axisLabelRender={handleAxisLabelRender}
/>

Note: Use PointersDirective, RangesDirective, and AnnotationsDirective child directives to configure pointers, ranges and annotations respectively. For full API details see Syncfusion docs: https://ej2.syncfusion.com/react/documentation/api/linear-gauge/index-default

Troubleshooting

Q: Ranges not appearing

• Verify start and end are within axis minimum and maximum
• Check color is valid (hex, rgb, or CSS color name)

Q: Annotation text overlapping

• Adjust x and y positions
• Use zIndex to reorder overlapping annotations

Q: Annotations shifting on resize

• Use percentage-based positioning (0-100) instead of pixels
• Test responsive behavior

Next Steps

• Read Customization for styling options
• Read Advanced Features for event handling and animations
• Read Accessibility for accessible range/annotation design