Skip to content

openvehicles/react-native-vehicle-gauges

BranchesTags

Repository files navigation

React Native Vehicle Gauges

A comprehensive suite of React Native components for displaying vehicle gauge clusters as seen in cars and motorcycles. Create stunning, customizable dashboard displays with authentic automotive styling.

DISCLAIMER

This is a very early version of this package, only recently released and only very recently making its way into a late stage development application. Production ready code is a while away. If you are not ready for this to not work, or for the next version to change the API in ways that will break your code, then please don't use this library.

That said, contributions are welcome - via the github repository.

N.B. Any bugs are probably the Cursor AI's, not mine.

Features

  • 🚗 Authentic Design: Components inspired by real vehicle dashboards
  • ⚡ High Performance: Optimized for smooth animations and real-time updates
  • 🎨 Fully Customizable: Colors, fonts, sizes, and styling options
  • 📱 React Native: Works on both iOS and Android
  • 🔧 TypeScript: Full type safety and IntelliSense support
  • 🏍️ Multiple Vehicle Types: Support for cars, motorcycles, and custom gauges

Installation

npm install react-native-vehicle-gauges react-native-svg

Note: If you encounter peer dependency conflicts during installation, use:

npm install react-native-vehicle-gauges react-native-svg --legacy-peer-deps

iOS Setup

For iOS, you need to install pods:

cd ios && pod install

Android Setup

No additional setup required for Android.

Components

GaugeSpeedometer

A customizable speedometer gauge with analog display and optional digital readout.

GaugeTachometer

A customizable tachometer (RPM) gauge with analog display and optional digital readout.

GaugeBattery

A customizable battery voltage gauge with analog display and optional digital readout.

Tachometer Features

  • Configurable RPM range (min/max)
  • Redline zone indication
  • Smart tick intervals based on RPM range
  • RPM display in thousands (e.g., 6000 RPM shows as "6")
  • Customizable colors and fonts
  • Optional digital RPM display
  • Responsive sizing

Battery Features

  • Half-circle design (180° arc from left to right, flat base)
  • Configurable voltage range (min/max)
  • Low voltage warning zone
  • Enhanced tick intervals with more frequent labels
  • Voltage display with decimal precision
  • Automotive-optimized defaults (10.0-16.0V)
  • Customizable colors and fonts
  • Optional digital voltage display
  • Responsive sizing

Speedometer Features

  • Configurable speed range (min/max)
  • Redline zone indication
  • Multiple unit support (mph/kph)
  • Customizable colors and fonts
  • Optional digital speed display
  • Responsive sizing

API Reference

Common Props (All Gauges)

Prop Type Default Description
size GaugeSize { width: '100%', height: '100%' } Gauge dimensions
theme 'light' | 'dark' | 'auto' 'auto' Theme mode with auto-detection
colors GaugeColors See below Color customization
fonts GaugeFonts See below Font customization
padding number 15 Border padding as percentage
label string varies Gauge label text (defaults vary by gauge type)

Common Props (Circular Gauges)

Prop Type Default Description
needleLength number calculated Needle length in pixels from center
tickLengthMajor number 15 Major tick length in pixels
tickLengthMinor number 8 Minor tick length in pixels
centerDotRadius number 8 Center dot radius in pixels
digitalDisplayPosition number varies Digital display position from bottom
labelPosition number varies Label position from bottom

GaugeSpeedometer Props

Prop Type Default Description
speed number 0 Current speed value
minSpeed number 0 Minimum speed on gauge
maxSpeed number 200 Maximum speed on gauge
redlineSpeed number none Speed at which redline zone begins
units 'mph' | 'kph' 'mph' Speed units
label string 'SPEED' Gauge label text
showDigitalSpeed boolean true Show digital speed display
digitalDisplayPosition number 40 Digital display position from bottom
labelPosition number 80 Label position from bottom

GaugeTachometer Props

Prop Type Default Description
rpm number 0 Current RPM value
minRpm number 0 Minimum RPM on gauge
maxRpm number 8000 Maximum RPM on gauge
redlineRpm number none RPM at which redline zone begins
label string 'RPM' Gauge label text
showDigitalRpm boolean true Show digital RPM display
digitalDisplayPosition number 40 Digital display position from bottom
labelPosition number 80 Label position from bottom
multiplierLabelPosition number 120 RPM multiplier label position from top

GaugeBattery Props

Prop Type Default Description
voltage number 12.0 Current voltage value
minVoltage number 10.0 Minimum voltage on gauge
maxVoltage number 16.0 Maximum voltage on gauge
lowVoltage number none Voltage at which warning zone begins
label string 'BATTERY' Gauge label text
showDigitalVoltage boolean true Show digital voltage display
digitalDisplayPosition number 35 Digital display position from bottom
labelPosition number 75 Label position from bottom

GaugeFuel Props

Prop Type Default Description
fuelLevel number 50.0 Current fuel level (0-100%)
tankCapacity number none Tank capacity for volume calculations
lowFuelThreshold number 25.0 Low fuel warning threshold
units 'percentage' | 'litres' | 'gallons' 'percentage' Display units
label string 'FUEL' Gauge label text
showDigitalLevel boolean true Show digital fuel level display
digitalDisplayPosition number 35 Digital display position from bottom
labelPosition number 75 Label position from bottom

GaugeTemperature Props

Prop Type Default Description
temperature number 20 Current temperature value
minTemperature number -40 Minimum temperature on gauge
maxTemperature number 120 Maximum temperature on gauge
lowTemperature number 0 Low temperature threshold (blue zone)
highTemperature number 100 High temperature threshold (red zone)
units 'celsius' | 'fahrenheit' 'celsius' Temperature units
label string 'TEMP' Gauge label text
showDigitalTemperature boolean true Show digital temperature display
digitalDisplayPosition number 35 Digital display position from bottom
labelPosition number 75 Label position from bottom

GaugeOilPressure Props

Prop Type Default Description
pressure number 30 Current pressure value
minPressure number 0 Minimum pressure on gauge
maxPressure number 100 Maximum pressure on gauge
lowPressure number 15 Low pressure threshold (red zone)
highPressure number 80 High pressure threshold (red zone)
units 'psi' | 'bar' | 'kpa' 'psi' Pressure units
label string 'OIL PRESSURE' Gauge label text
showDigitalPressure boolean true Show digital pressure display
digitalDisplayPosition number 35 Digital display position from bottom
labelPosition number 75 Label position from bottom

GaugeGear Props

Prop Type Default Description
currentGear string 'P' Currently selected gear
gears string[] ['P', 'R', 'N', 'D'] Available gears array
orientation 'portrait' | 'landscape' 'portrait' Layout orientation
label string 'GEAR' Gauge label text
gearSize number 45 Individual gear circle size in pixels
connectingLineThickness number 8 Line thickness between gears
gearMargin number 1 Margin between gears
borderRadius number 15 Container border radius

Color Options

interface GaugeColors {
  background?: string;
  needle?: string;
  tickMajor?: string;
  tickMinor?: string;
  numbers?: string;
  redline?: string;
  digitalSpeed?: string;
  arc?: string;
}

Font Options

interface GaugeFonts {
  numbers?: {
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: string;
  };
  digitalSpeed?: {
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: string;
  };
  units?: {
    fontSize?: number;
    fontFamily?: string;
    fontWeight?: string;
  };
}

Usage

Basic Usage

import React from 'react';
import { View } from 'react-native';
import { 
  GaugeSpeedometer, 
  GaugeTachometer, 
  GaugeBattery,
  GaugeFuel,
  GaugeTemperature,
  GaugeOilPressure,
  GaugeGear 
} from 'react-native-vehicle-gauges';

export default function App() {
  const [speed, setSpeed] = React.useState(65);
  const [rpm, setRpm] = React.useState(3500);
  const [voltage, setVoltage] = React.useState(12.6);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <GaugeSpeedometer
        speed={speed}
        maxSpeed={180}
        redlineSpeed={140}
        units="mph"
        size={{ width: 300, height: 300 }}
      />
      
      <GaugeTachometer
        rpm={rpm}
        maxRpm={8000}
        redlineRpm={6500}
        size={{ width: 300, height: 300 }}
      />
      
      <GaugeBattery
        voltage={voltage}
        lowVoltage={12.0}
        size={{ width: 300, height: 150 }}
      />
    </View>
  );
}

Advanced Customization

import React from 'react';
import { View } from 'react-native';
import { GaugeSpeedometer } from 'react-native-vehicle-gauges';

export default function CustomSpeedometer() {
  const [speed, setSpeed] = React.useState(85);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <GaugeSpeedometer
        speed={speed}
        minSpeed={0}
        maxSpeed={200}
        redlineSpeed={160}
        units="kph"
        size={{ width: 350, height: 350 }}
        theme="dark"
        
        // Visual customization
        needleLength={120}         // Custom needle length
        tickLengthMajor={20}       // Longer major ticks
        tickLengthMinor={10}       // Longer minor ticks
        centerDotRadius={12}       // Larger center dot
        digitalDisplayPosition={45} // Move digital display
        padding={10}               // Tighter padding
        
        // Colors
        colors={{
          background: '#000000',
          needle: '#FF6B35',
          tickMajor: '#FFFFFF',
          tickMinor: '#888888',
          numbers: '#FFFFFF',
          redline: '#FF1744',
          digitalSpeed: '#00E676',
          arc: '#424242'
        }}
        
        // Fonts
        fonts={{
          numbers: {
            fontSize: 18,
            fontFamily: 'System',
            fontWeight: 'bold'
          },
          digitalSpeed: {
            fontSize: 28,
            fontFamily: 'System',
            fontWeight: 'bold'
          }
        }}
      />
    </View>
  );
}

Multi-Gauge Dashboard

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { 
  GaugeSpeedometer,
  GaugeTachometer,
  GaugeFuel,
  GaugeTemperature,
  GaugeGear 
} from 'react-native-vehicle-gauges';

export default function Dashboard() {
  return (
    <View style={styles.dashboard}>
      {/* Main gauges */}
      <View style={styles.mainGauges}>
        <GaugeSpeedometer
          speed={75}
          maxSpeed={180}
          size={{ width: 200, height: 200 }}
          padding={10}
        />
        <GaugeTachometer
          rpm={3500}
          maxRpm={8000}
          redlineRpm={6500}
          size={{ width: 200, height: 200 }}
          padding={10}
        />
      </View>
      
      {/* Secondary gauges */}
      <View style={styles.secondaryGauges}>
        <GaugeFuel
          fuelLevel={65}
          lowFuelThreshold={20}
          units="percentage"
          size={{ width: 150, height: 100 }}
          digitalDisplayPosition={25}
          labelPosition={50}
        />
        <GaugeTemperature
          temperature={85}
          highTemperature={100}
          units="celsius"
          size={{ width: 150, height: 100 }}
          digitalDisplayPosition={25}
          labelPosition={50}
        />
      </View>
      
      {/* Gear selector */}
      <GaugeGear
        currentGear="D"
        gears={['P', 'R', 'N', 'D', 'S']}
        orientation="landscape"
        size={{ width: 250, height: 80 }}
        gearSize={35}
        connectingLineThickness={6}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  dashboard: {
    flex: 1,
    padding: 20,
    justifyContent: 'space-around',
    alignItems: 'center',
  },
  mainGauges: {
    flexDirection: 'row',
    justifyContent: 'space-around',
    width: '100%',
  },
  secondaryGauges: {
    flexDirection: 'row',
    justifyContent: 'space-around',
    width: '100%',
  },
});

Theming

The gauge library includes a powerful theming system that automatically detects your app's theme and provides beautiful defaults while allowing full customization.

Automatic Theme Detection

The gauges automatically detect themes from:

  • React Navigation: @react-navigation/native
  • React Native Paper: react-native-paper

Theme Usage

// Automatic theme detection (recommended)
<GaugeSpeedometer speed={65} />

// Explicit theme
<GaugeSpeedometer speed={65} theme="dark" />

// Theme with custom colors
<GaugeSpeedometer 
  speed={65}
  theme="auto"
  colors={{
    needle: '#ff6b35', // Custom orange needle
    redline: '#ff1744'  // Custom red redline
  }}
/>

Theme Options

  • 'auto' (default): Automatically detects current app theme
  • 'light': Forces light theme
  • 'dark': Forces dark theme

Built-in Themes

Light Theme:

  • Background: #ffffff
  • Arc: #e0e0e0
  • Needle: #2196f3
  • Text: #333333

Dark Theme:

  • Background: #1a1a1a
  • Arc: #333333
  • Needle: #00ff00
  • Text: #ffffff

Examples

Check out the examples/ directory for complete implementation examples:

  • BasicSpeedometer: Simple speedometer setup
  • CustomizedSpeedometer: Advanced customization options
  • AnimatedSpeedometer: Animated speed changes
  • TachometerExample: Complete tachometer demonstrations
  • BatteryExample: Battery voltage monitoring with status indicators

Development

# Install dependencies
npm install

# Build the library
npm run build

# Watch for changes during development
npm run dev

# Run linting
npm run lint

# Run tests
npm run test

Contributing

We welcome contributions! Please read our contributing guidelines and submit pull requests to help improve this library.

Development

Building the Library

# Build TypeScript to dist/
npm run build

# Watch mode for development
npm run dev

Running Examples

# Start web demo
npm run web

# Build web demo for production
npm run web:build

Publishing

The library follows npm best practices:

  1. Build files are included in Git for reliability
  2. Automatic build before publish via prepublishOnly script
  3. Full TypeScript support with declaration files

To publish a new version:

# Update version in package.json
npm version patch  # or minor, major

# Build and publish (build runs automatically)
npm publish

# Push version tag to Git
git push --tags

License

MIT License - see the LICENSE file for details.

Roadmap

  • Speedometer gauge ✅ Completed
  • Tachometer gauge ✅ Completed
  • Battery voltage gauge ✅ Completed
  • Fuel gauge ✅ Completed
  • Temperature gauge ✅ Completed
  • Oil pressure gauge ✅ Completed
  • Gear selector ✅ Completed
  • Theme system ✅ Completed
  • Advanced customization ✅ Completed
  • Production-ready library ✅ Completed

Future Enhancements

  • Multi-gauge cluster layouts
  • Animation presets and transitions
  • Additional vehicle-specific gauges
  • Performance monitoring and analytics

Support

If you encounter any issues or have questions, please file an issue on our GitHub repository.

About

A react native NPM module implementing several gauges for use in glass vehicle clusters (or OVMS-X app)

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

7 tags

Packages

 
 
 

Contributors

Languages