syncfusion-react-linear-gauge

What this skill does

# 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](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](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](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](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](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](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:

```tsx
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:
```bash
npm install @syncfusion/ej2-react-lineargauge --save
```

---

## Common Patterns

### Pattern 1: Simple Temperature Gauge
```tsx
<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
```tsx
<PointersDirective>
  <PointerDirective 
    value={75} 
    type='Marker'
    markerType='Rectangle'
    width={20}
    color='#007AFF'
  />
</PointersDirective>
```

### Pattern 3: Real-Time Updates
```tsx
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)**

| Prop | Type | Purpose | Example |
|------|------|---------|---------|
| `title` | string | Gauge title text | `title="Temperature"` |
| `orientation` | "Horizontal" \| "Vertical" | Layout orientation (default: Vertical) | `orientation="Horizontal"` |
| `width` | string | Gauge width | `width="100%"` or `width="400px"` |
| `height` | string | Gauge height | `height="300px"` |

---

## AxisDirective API Reference

### **Verified Props for AxisDirective**

| Prop | Type | Purpose | Example |
|------|------|---------|---------|
| `minimum` | number | Start value of the axis range | `minimum={0}` |
| `maximum` | number | End value of the axis range | `maximum={200}` |
| `labelStyle` | object | Label customization (use `format` property) | `labelStyle={{ format: '{value}°C' }}` |

### **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**

| Prop | Type | Purpose | Example |
|------|------|---------|---------|
| `value` | number | The value to display | `value={140}` |
| `color` |