@fseehawer/react-circular-slider
Version:
A customizable circular slider with no dependencies.
171 lines (139 loc) • 12.7 kB
Markdown
# react-circular-slider
[](https://github.com/fseehawer/react-circular-slider)
[](https://opensource.org/licenses/MIT)
A highly customizable circular slider with **zero dependencies**. Check out the [live demos](https://fseehawer.github.io/react-circular-slider/)!
<img src="https://fseehawer.github.io/react-circular-slider/circular-slider.png" alt="An image showing the CircularSlider settings" width="100%" />
## TypeScript Support
This component now has full **TypeScript** support! Enjoy full IntelliSense and strong type-checking out of the box.
*JavaScript users: No worries – the published output is plain JavaScript and works exactly as before.*
## Installation
```bash
npm install @fseehawer/react-circular-slider
```
## example
```javascript
import React from 'react';
import CircularSlider from '@fseehawer/react-circular-slider';
const App: React.FC = () => (
<>
<CircularSlider onChange={value => console.log(value)} />
</>
);
export default App;
```
## Custom Configuration
Customize properties such as the label, colors, data set, and more:
```javascript
import React from 'react';
import CircularSlider from '@fseehawer/react-circular-slider';
const App: React.FC = () => (
<>
<CircularSlider
label="savings"
labelColor="#005a58"
knobColor="#005a58"
progressColorFrom="#00bfbd"
progressColorTo="#009c9a"
progressSize={24}
trackColor="#eeeeee"
trackSize={24}
data={['1€', '2€']} // Custom data array
dataIndex={10}
onChange={value => console.log(value)}
/>
</>
);
export default App;
```
## Props
The table below lists all available props along with their TypeScript types, default values, and descriptions.
| Prop | Type | Default | Description |
|---------------------------|---------------------------------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------|
| `width` | `number` | `280` | Width of the slider in pixels. |
| `direction` | `1 \| -1` | `1` | Rotation direction: `1` for clockwise, `-1` for anticlockwise. |
| `min` | `number` | `0` | Minimum value. |
| `max` | `number` | `360` | Maximum value. |
| `initialValue` | `number` | `0` | Initial value for the label. |
| `data` | `(string \| number)[]` | `[]` | Array of values or labels, evenly spread over 360°. |
| `dataIndex` | `number` | `0` | Initial index position in the data array. |
| `knobColor` | `string` | `"#4e63ea"` | Color of the knob. |
| `knobSize` | `number` | `32` | Diameter of the knob in pixels. |
| `hideKnob` | `boolean` | `false` | If `true`, the knob is hidden. |
| `hideKnobRing` | `boolean` | `false` | If `true`, the translucent ring around the knob is hidden. |
| `knobDraggable` | `boolean` | `true` | If `true`, the knob is draggable. |
| `knobPosition` | `string \| number` | `"top"` | Starting position: accepts `"top"`, `"right"`, `"bottom"`, `"left"` or an angle (in degrees). |
| `label` | `string` | `"ANGLE"` | Text label displayed on the slider. |
| `labelColor` | `string` | `"#272b77"` | Color of the label and value text. |
| `labelBottom` | `boolean` | `false` | If `true`, the label is positioned below the slider. |
| `labelFontSize` | `string` | `"1rem"` | Font size of the label. |
| `valueFontSize` | `string` | `"4rem"` | Font size of the displayed value. |
| `appendToValue` | `string` | `""` | Text appended to the value. |
| `prependToValue` | `string` | `""` | Text prepended to the value. |
| `renderLabelValue` | `React.ReactNode` | `null` | Custom JSX for rendering the label and value. |
| `verticalOffset` | `string` | `"2rem"` | Vertical offset for the label/value display. |
| `hideLabelValue` | `boolean` | `false` | If `true`, both the label and value are hidden. |
| `progressColorFrom` | `string` | `"#80C3F3"` | Start color for the progress gradient. |
| `progressColorTo` | `string` | `"#4990E2"` | End color for the progress gradient. |
| `progressSize` | `number` | `8` | Thickness of the progress track. |
| `progressLineCap` | `"round" \| "butt"` | `"round"` | Cap style for the progress track. |
| `trackColor` | `string` | `"#DDDEFB"` | Color of the background track. |
| `trackSize` | `number` | `8` | Thickness of the background track. |
| `trackDraggable` | `boolean` | `false` | If `true`, allows dragging the background track. |
| `progressGradient` | `(string \| GradientStop)[]` | `undefined` | Array of color stops for a multi-stop progress gradient. Overrides `progressColorFrom`/`To`. Each stop can be a color string or `{ offset, stopColor, stopOpacity }`. |
| `trackGradient` | `(string \| GradientStop)[]` | `undefined` | Array of color stops for a multi-stop track gradient. Overrides `trackColor`. |
| `arcStart` | `number` | `undefined` | Start angle (in degrees) for arc mode. Use with `arcEnd` to create a partial-circle gauge (e.g. `225` for lower-left). |
| `arcEnd` | `number` | `undefined` | End angle (in degrees) for arc mode. Use with `arcStart` (e.g. `135` for lower-right = 270° speedometer sweep). |
| `onChange` | `(value: string \| number) => void` | `() => {}` | Callback fired when the value changes. |
| `isDragging` | `(dragging: boolean) => void` | `() => {}` | Callback to signal whether the slider is being dragged. |
## Multi-Stop Gradient Example
Use `progressGradient` and/or `trackGradient` for rich multi-color arcs:
```jsx
<CircularSlider
label="Spectrum"
min={0}
max={360}
dataIndex={180}
progressGradient={[
{ offset: '0%', stopColor: '#ef4444' },
{ offset: '20%', stopColor: '#f97316' },
{ offset: '40%', stopColor: '#eab308' },
{ offset: '55%', stopColor: '#22c55e' },
{ offset: '70%', stopColor: '#3b82f6' },
{ offset: '85%', stopColor: '#6366f1' },
{ offset: '100%', stopColor: '#8b5cf6' },
]}
trackGradient={[
{ offset: '0%', stopColor: '#fecaca', stopOpacity: 0.4 },
{ offset: '50%', stopColor: '#bbf7d0', stopOpacity: 0.4 },
{ offset: '100%', stopColor: '#c4b5fd', stopOpacity: 0.4 },
]}
progressSize={12}
trackSize={12}
/>
```
## Arc (Gauge) Example
Use `arcStart` and `arcEnd` to create a partial-circle gauge, like a car speedometer:
```jsx
<CircularSlider
label="km/h"
min={0}
max={250}
dataIndex={80}
progressGradient={[
{ offset: '0%', stopColor: '#22c55e' },
{ offset: '50%', stopColor: '#eab308' },
{ offset: '100%', stopColor: '#dc2626' },
]}
progressSize={14}
trackColor="#e5e7eb"
trackSize={14}
progressLineCap="butt"
arcStart={225}
arcEnd={135}
/>
```
## Donation
If you find this component useful, please consider a small donation. Even one dollar helps maintain and develop new features!
[You can find the donate button on the bottom of the example page](https://fseehawer.github.io/react-circular-slider/)
## license
[MIT License](https://opensource.org/licenses/MIT)