A customizable gauge/speedometer component for React applications
npm install @kjanat/react-gauge-componentA customizable, animated gauge/speedometer component for React applications. Perfect for dashboards, analytics displays, and progress indicators.
- ðĻ Fully customizable appearance
- ð Multiple display modes (percentage, value, custom)
- ð Configurable color segments
- ð Adjustable size and thickness
- ðŊ Smooth needle animations
- ðą Responsive design
- ðŠ TypeScript support
- ðŠķ Lightweight with no dependencies

``bash`
npm install @kjanat/react-gauge-componentor
yarn add @kjanat/react-gauge-componentor
pnpm add @kjanat/react-gauge-component
`jsx
import { Gauge } from '@kjanat/react-gauge-component';
import '@kjanat/react-gauge-component/dist/styles.css';
function App() {
return
}
`
| Prop | Type | Default | Description |
| --------------- | ------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------- |
| value | number | 2.5 | Current value to display |min
| | number | 0 | Minimum value of the gauge |max
| | number | 5 | Maximum value of the gauge |label
| | string | '' | Label text displayed below the gauge |displayType
| | 'percentage' \| 'value' \| 'custom' | 'percentage' | How to display the current value |customDisplay
| | (value: number) => string | null | Custom function to format the display value |tickInterval
| | number | 1 | Interval between tick marks |showTicks
| | boolean | true | Whether to show tick marks and labels |colors
| | string[] | ['#22c55e', '#10b981', '#84cc16', '#eab308', '#f59e0b', '#ef4444'] | Array of colors for gauge segments |size
| | number | 300 | Width of the gauge in pixels |thickness
| | number | 40 | Thickness of the gauge arc |className
| | string | '' | Additional CSS class for styling |lightTheme
| | ThemeColors | See below | Custom colors for light mode |darkTheme
| | ThemeColors | See below | Custom colors for dark mode |autoDetectTheme
| | boolean | true | Automatically detect and apply dark mode |showTextOutline
| | boolean | true | Show text outline effect on value text |
`jsx`
`jsx`
`jsx${val} km/h
min={0}
max={100}
label="Speed"
displayType="custom"
customDisplay={(val) => }`
/>
`jsx`
min={0}
max={10}
label="Rating"
colors={['#ef4444', '#f59e0b', '#22c55e']}
tickInterval={2}
/>
`jsx
// Small gauge
// Large gauge
`
The component automatically detects dark mode based on:
- Tailwind's dark class on or
- System preference via prefers-color-scheme: dark`jsx
// Automatic dark mode detection (default)
// Custom theme colors
value={3.5}
min={0}
max={5}
lightTheme={{
background: '#f3f4f6',
tickColor: '#6b7280',
needleColor: '#111827',
needleCenter: '#e5e7eb',
textOutline: '#ffffff'
}}
darkTheme={{
background: '#111827',
tickColor: '#d1d5db',
needleColor: '#f9fafb',
needleCenter: '#4b5563',
textOutline: '#000000'
}}
/>
// Disable automatic theme detection
`#### ThemeColors Interface
`typescript
interface ThemeColors {
background?: string; // Inner arc background
tickColor?: string; // Tick marks color
needleColor?: string; // Needle body color
needleCenter?: string; // Needle center dot color
textOutline?: string; // Text outline effect color
valueTextColor?: string; // Value text color (auto-contrasts with background if not set)
}
`Styling
The component comes with default styles that you need to import:
`jsx
import '@kjanat/react-gauge-component/dist/styles.css';
`You can override the default styles using the
className prop or by targeting the component's CSS classes:-
.gauge-container - Main container
- .gauge-svg - SVG element
- .gauge-tick-label - Tick mark labels
- .gauge-value - Value display
- .gauge-label - Label textDevelopment
`bash
Install dependencies
pnpm installRun development server with examples
pnpm devBuild the library
pnpm build:libType checking
pnpm type-checkRun linting
pnpm lintRun unit tests
pnpm testRun E2E tests
pnpm test:e2e
`Testing
This project includes comprehensive test coverage:
$3
Unit tests are written with Vitest and React Testing Library:
`bash
Run tests once
pnpm testRun tests in watch mode
pnpm test:watchRun tests with UI
pnpm test:uiRun tests with coverage
pnpm test:coverage
`$3
End-to-end tests are written with Playwright to verify dark mode functionality across browsers:
`bash
Run E2E tests
pnpm test:e2eRun E2E tests with UI mode
pnpm test:e2e:uiDebug E2E tests
pnpm test:e2e:debugShow test report
pnpm test:e2e:report
`The E2E tests verify:
- Dark mode detection and theme switching
- Color values in different themes
- Text visibility and contrast
- Manual theme override behavior
- Cross-browser compatibility (Chrome, Firefox, Safari)
Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
License
MIT ÂĐ Kaj Kowalski
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)- Initial release
- Basic gauge functionality
- TypeScript support
- Multiple display modes
- Customizable colors and sizes