@toankhontech/arctimer-react 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +153 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# @toankhontech/arctimer-react
|
|
2
|
+
|
|
3
|
+
Smooth, 60fps countdown circle timer for React.
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://raw.githubusercontent.com/toankhontech/arc-timer/main/assets/demo.gif" alt="ArcTimer Demo" width="600" />
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
Part of the [ArcTimer](https://github.com/toankhontech/arc-timer) monorepo. Also available for [React Native](https://www.npmjs.com/package/@toankhontech/arctimer-react-native) and [Expo](https://www.npmjs.com/package/@toankhontech/arctimer-expo).
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @toankhontech/arctimer-react
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Quick Start
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
import { CountdownCircleTimer } from '@toankhontech/arctimer-react'
|
|
21
|
+
|
|
22
|
+
function App() {
|
|
23
|
+
return (
|
|
24
|
+
<CountdownCircleTimer
|
|
25
|
+
isPlaying
|
|
26
|
+
duration={60}
|
|
27
|
+
colors={['#3498DB', '#F39C12', '#E74C3C']}
|
|
28
|
+
colorsTime={[60, 30, 0]}
|
|
29
|
+
>
|
|
30
|
+
{({ remainingTime, color }) => (
|
|
31
|
+
<span style={{ color, fontSize: 32 }}>{remainingTime}</span>
|
|
32
|
+
)}
|
|
33
|
+
</CountdownCircleTimer>
|
|
34
|
+
)
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Props
|
|
39
|
+
|
|
40
|
+
| Prop | Type | Default | Description |
|
|
41
|
+
|------|------|---------|-------------|
|
|
42
|
+
| `duration` | `number` | **required** | Duration in seconds |
|
|
43
|
+
| `isPlaying` | `boolean` | `false` | Start/stop the timer |
|
|
44
|
+
| `colors` | `string \| string[]` | `'#3498DB'` | Single color or array for gradient |
|
|
45
|
+
| `colorsTime` | `number[]` | auto | Time thresholds for color transitions |
|
|
46
|
+
| `size` | `number` | `180` | Width and height in px |
|
|
47
|
+
| `strokeWidth` | `number` | `12` | Arc stroke width |
|
|
48
|
+
| `trailColor` | `string` | `'#d9d9d9'` | Background circle color |
|
|
49
|
+
| `easing` | `string \| object` | `'linear'` | `'linear'`, `'easeIn'`, `'easeOut'`, `'easeInOut'`, or spring config |
|
|
50
|
+
| `isCountUp` | `boolean` | `false` | Count up instead of down |
|
|
51
|
+
| `initialRemainingTime` | `number` | — | Start from a specific time |
|
|
52
|
+
| `children` | `(info) => ReactNode` | — | Render function for center content |
|
|
53
|
+
| `onComplete` | `() => void \| { shouldRepeat, delay }` | — | Fires when timer reaches zero |
|
|
54
|
+
| `onUpdate` | `(remainingTime) => void` | — | Fires every second |
|
|
55
|
+
|
|
56
|
+
### Animation Effects
|
|
57
|
+
|
|
58
|
+
| Prop | Type | Description |
|
|
59
|
+
|------|------|-------------|
|
|
60
|
+
| `bounceOnComplete` | `boolean` | Scale bounce when timer completes |
|
|
61
|
+
| `bounceAt` | `number[]` | Bounce at specific remaining times (e.g. `[10, 5]`) |
|
|
62
|
+
| `pulse` | `{ interval, scale, opacity }` | Periodic breathing animation |
|
|
63
|
+
|
|
64
|
+
### Render Function
|
|
65
|
+
|
|
66
|
+
The `children` render function receives:
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
{
|
|
70
|
+
remainingTime: number // seconds left (integer)
|
|
71
|
+
elapsedTime: number // seconds elapsed (integer)
|
|
72
|
+
color: string // current interpolated color
|
|
73
|
+
progress: number // 0 to 1
|
|
74
|
+
isComplete: boolean // true when timer is done
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Imperative API
|
|
79
|
+
|
|
80
|
+
Control the timer programmatically via ref:
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
import { useRef } from 'react'
|
|
84
|
+
import { CountdownCircleTimer, type TimerRef } from '@toankhontech/arctimer-react'
|
|
85
|
+
|
|
86
|
+
function App() {
|
|
87
|
+
const timerRef = useRef<TimerRef>(null)
|
|
88
|
+
|
|
89
|
+
return (
|
|
90
|
+
<>
|
|
91
|
+
<CountdownCircleTimer ref={timerRef} duration={60} colors="#3498DB">
|
|
92
|
+
{({ remainingTime }) => remainingTime}
|
|
93
|
+
</CountdownCircleTimer>
|
|
94
|
+
<button onClick={() => timerRef.current?.pause()}>Pause</button>
|
|
95
|
+
<button onClick={() => timerRef.current?.play()}>Play</button>
|
|
96
|
+
<button onClick={() => timerRef.current?.reset()}>Reset</button>
|
|
97
|
+
</>
|
|
98
|
+
)
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Multi-Timer (Sequential / Parallel)
|
|
103
|
+
|
|
104
|
+
Run timers one after another, or all at once:
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
import { TimerGroup, CountdownCircleTimer } from '@toankhontech/arctimer-react'
|
|
108
|
+
|
|
109
|
+
<TimerGroup mode="sequential" isPlaying onGroupComplete={() => alert('Done!')}>
|
|
110
|
+
<CountdownCircleTimer duration={1500} colors="#E74C3C" />
|
|
111
|
+
<CountdownCircleTimer duration={300} colors="#2ECC71" />
|
|
112
|
+
</TimerGroup>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Theming
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
import { TimerThemeProvider, darkTheme } from '@toankhontech/arctimer-themes'
|
|
119
|
+
|
|
120
|
+
<TimerThemeProvider theme={darkTheme}>
|
|
121
|
+
<CountdownCircleTimer duration={60} colors="#00D2FF" />
|
|
122
|
+
</TimerThemeProvider>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
5 built-in themes: `defaultTheme`, `darkTheme`, `minimalTheme`, `vibrantTheme`, `neonTheme`
|
|
126
|
+
|
|
127
|
+
## Easing & Spring Physics
|
|
128
|
+
|
|
129
|
+
```tsx
|
|
130
|
+
// Built-in easing
|
|
131
|
+
<CountdownCircleTimer easing="easeInOut" ... />
|
|
132
|
+
|
|
133
|
+
// Spring physics
|
|
134
|
+
<CountdownCircleTimer easing={{ type: 'spring', tension: 170, friction: 26 }} ... />
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Migrating from react-countdown-circle-timer
|
|
138
|
+
|
|
139
|
+
Drop-in replacement:
|
|
140
|
+
|
|
141
|
+
```diff
|
|
142
|
+
- import { CountdownCircleTimer } from 'react-countdown-circle-timer'
|
|
143
|
+
+ import { CountdownCircleTimer } from '@toankhontech/arctimer-react'
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Links
|
|
147
|
+
|
|
148
|
+
- [GitHub](https://github.com/toankhontech/arc-timer)
|
|
149
|
+
- [Full API Reference](https://github.com/toankhontech/arc-timer/blob/main/docs/docs/api-reference.md)
|
|
150
|
+
|
|
151
|
+
## License
|
|
152
|
+
|
|
153
|
+
MIT
|