Skip to content

Commit 0c71e79

Browse files
vydimitrovvydimitrov
committed
chore: update README for all packages
1 parent 104e0ae commit 0c71e79

File tree

3 files changed

+13
-226
lines changed

3 files changed

+13
-226
lines changed

‎README.md‎

Lines changed: 2 additions & 219 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ React/React Native countdown timer component in a circle shape with color and pr
44

55
<img src="https://user-images.githubusercontent.com/10707142/66097204-ca68c200-e59d-11e9-9b70-688409755aaa.gif" width="200"> <img src="https://user-images.githubusercontent.com/10707142/65935516-a0869280-e419-11e9-9bb0-40c4d1ef2bbe.gif" width="200"> <img src="https://user-images.githubusercontent.com/10707142/65963815-cfbdf380-e45b-11e9-809d-970174e88914.gif" width="200">
66

7+
## Features
8+
79
:zap: Performance optimized with single `requestAnimationFrame` loop to animate color and progress
810
:rainbow: Transition between colors during the countdown
911
:european_castle: Fully customizable content in the center of the circle
@@ -34,222 +36,3 @@ yarn add react-native-countdown-circle-timer
3436
```
3537

3638
This component has a peer dependency on `react-native-svg`. Read the [full documentation](https://github.com/vydimitrov/react-countdown-circle-timer/tree/master/packages/mobile#react-native-countdown-circle-timer) for the installation guide, as well as demos and use cases.
37-
38-
## Demo
39-
40-
### React
41-
42-
Check the [CodeSandbox](https://codesandbox.io/s/stoic-cache-e7cie?fontsize=14&hidenavigation=1&theme=dark) demo to get started.
43-
44-
```jsx
45-
import { CountdownCircleTimer } from 'react-countdown-circle-timer'
46-
47-
const UrgeWithPleasureComponent = () => (
48-
<CountdownCircleTimer
49-
isPlaying
50-
duration={7}
51-
colors={['#004777', '#F7B801', '#A30000', '#A30000']}
52-
colorsTime={[7, 5, 2, 0]}
53-
>
54-
{({ remainingTime }) => remainingTime}
55-
</CountdownCircleTimer>
56-
)
57-
```
58-
59-
### React Native
60-
61-
Check the [Expo Snack](https://snack.expo.io/@dimitrov/countdown-circle-timer?platform=ios) demo to get started.
62-
63-
```jsx
64-
import { Text } from 'react-native'
65-
import { CountdownCircleTimer } from 'react-native-countdown-circle-timer'
66-
67-
const UrgeWithPleasureComponent = () => (
68-
<CountdownCircleTimer
69-
isPlaying
70-
duration={7}
71-
colors={['#004777', '#F7B801', '#A30000', '#A30000']}
72-
colorsTime={[7, 5, 2, 0]}
73-
>
74-
{({ remainingTime }) => <Text>{remainingTime}</Text>}
75-
</CountdownCircleTimer>
76-
)
77-
```
78-
79-
### Hook
80-
81-
Both the React and React Native packages export a hook `useCountdown`, which accepts the same props as the component and returns all props needed to render your own circle.
82-
83-
```jsx
84-
import { useCountdown } from 'react-countdown-circle-timer'
85-
86-
const {
87-
path,
88-
pathLength,
89-
stroke,
90-
strokeDashoffset,
91-
remainingTime,
92-
elapsedTime,
93-
size,
94-
strokeWidth,
95-
} = useCountdown({ isPlaying: true, duration: 7, colors: '#abc' })
96-
```
97-
98-
## Props
99-
100-
| Prop Name | Type | Default | Description |
101-
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102-
| duration | number | _required_ | Countdown duration in seconds |
103-
| colors | string \| string[] | _required_ | `colors` prop is either:<br> - Single valid color in any format or URL to a gradient<br> - Array of colors in HEX format. At least 2 colors should be provided |
104-
| colorsTime | number[] | - | Indicates the time when a color should switch to the next color. The first number is the countdown duration and the last one is 0 or goal. Works only when `colors` is an array of HEX colors |
105-
| isPlaying | boolean | false | Play or pause animation |
106-
| initialRemainingTime | number | - | Set the initial remaining time if it is different than the duration |
107-
| updateInterval | number | 0 | Update interval in seconds. Determines how often the timer updates. When set to 0 the value will update on each key frame |
108-
| size | number | 180 | Width and height of the SVG element |
109-
| strokeWidth | number | 12 | Path stroke width |
110-
| trailStrokeWidth | number | strokeWidth | Trail stroke width |
111-
| strokeLinecap | round \| square | round | Path stroke line cap |
112-
| rotation | clockwise \| counterclockwise | clockwise | Progress path rotation direction |
113-
| trailColor | string | #d9d9d9 | Circle trail color - takes any valid color format |
114-
| isSmoothColorTransition | boolean | true | Indicates if the colors should smoothly transition to the next color |
115-
| children | (props: { remainingTime: number, elapsedTime: number, color: string }) => ReactNode | - | Render function to customize the time/content in the center of the circle |
116-
| onComplete | (totalElapsedTime: number) => void \| { shouldRepeat: boolean, delay?: number, newInitialRemainingTime?: number } | - | On animation complete event handler |
117-
| onUpdate | (remainingTime: number) => void | - | On remaining time update event handler |
118-
119-
## Browser support
120-
121-
The component and hook support [all modern browsers](https://caniuse.com/?search=es6) targeting `es6`. Internet Explorer (IE) is not longer supported.
122-
123-
## Recipes
124-
125-
### Changing `duration` prop
126-
127-
Once the component is mounted the `duration` prop can be changed the the timer will respect the new duration. In case the new duration is bigger than the previous one then the timer will continue to the new duration. In case the new duration is smaller then the previous one then the timer will ne over. If you want to restart the timer when the duration changes then pass a new `key` prop to `CountdownCircleTimer` component and the timer will start over with the new values provided.
128-
129-
### Restart/Reset timer at any given time
130-
131-
Pass a `key` prop to `CountdownCircleTimer` and change the `key` when the timer should be restarted. Check [this demo](https://codesandbox.io/s/tender-bogdan-qd35m) to find out one possible implementation.
132-
133-
### Repeat timer when countdown is completed
134-
135-
Return an object from `onComplete` handler, which indicates if the animation should be repeated. Example:
136-
137-
```jsx
138-
const UrgeWithPleasureComponent = () => (
139-
<CountdownCircleTimer
140-
isPlaying
141-
duration={10}
142-
colors="#A30000"
143-
onComplete={() => {
144-
// do your stuff here
145-
return { shouldRepeat: true, delay: 1.5 } // repeat animation in 1.5 seconds
146-
}}
147-
/>
148-
)
149-
```
150-
151-
### Set the initial remaining time different then the duration provided
152-
153-
Pass the remaining time to `initialRemainingTime` prop. Example:
154-
155-
```jsx
156-
const UrgeWithPleasureComponent = () => (
157-
<CountdownCircleTimer
158-
isPlaying
159-
duration={60}
160-
initialRemainingTime={15}
161-
colors="#A30000"
162-
/>
163-
)
164-
```
165-
166-
In the example above, the countdown will start at 15 seconds (one quarter before it's done) and it will animate for 15 seconds until reaches 0.
167-
168-
### Time formatting functions
169-
170-
`children` prop of `CountdownCircleTimer` component will receive as a prop `remainingTime` in seconds. Below are a few functions that can be used to get different time formatting:
171-
172-
- Format `mm:ss` (minutes and seconds)
173-
174-
```js
175-
const children = ({ remainingTime }) => {
176-
const minutes = Math.floor(remainingTime / 60)
177-
const seconds = remainingTime % 60
178-
179-
return `${minutes}:${seconds}`
180-
}
181-
```
182-
183-
- Format `hh:mm:ss` (hours, minutes and seconds)
184-
185-
```js
186-
const children = ({ remainingTime }) => {
187-
const hours = Math.floor(remainingTime / 3600)
188-
const minutes = Math.floor((remainingTime % 3600) / 60)
189-
const seconds = remainingTime % 60
190-
191-
return `${hours}:${minutes}:${seconds}`
192-
}
193-
```
194-
195-
### Add `a11y` support
196-
197-
#### React
198-
199-
- Wrapper the timer in an element and add the following attribute `aria-label={your-aria-label}`
200-
- Add the following element with `role="timer"` to your `children` function that will make the screen reader read the remaining time while the timer is running.
201-
202-
```jsx
203-
const children = ({ remainingTime }) => (
204-
<div role="timer" aria-live="assertive">
205-
{remainingTime} seconds
206-
</div>
207-
)
208-
```
209-
210-
#### React Native
211-
212-
- Wrapper the timer in an `View` element and add the following attributes `accessible={true} accessibilityLabel={your-aria-abel}`
213-
- Add the following `Text` element to your `children` function that will make the screen reader read the remaining time while the timer is running.
214-
215-
```jsx
216-
const children = ({ remainingTime }) => (
217-
<Text
218-
accessibilityRole="timer"
219-
accessibilityLiveRegion="assertive"
220-
importantForAccessibility="yes"
221-
>
222-
{remainingTime} seconds
223-
</Text>
224-
)
225-
```
226-
227-
### Add gradient
228-
229-
Define the SVG gradient outside the Timer component and pass the gradient ID to the Timer component as a single color:
230-
231-
```jsx
232-
<svg>
233-
<defs>
234-
<linearGradient id="your-unique-id" x1="1" y1="0" x2="0" y2="0">
235-
<stop offset="5%" stopColor="gold" />
236-
<stop offset="95%" stopColor="red" />
237-
</linearGradient>
238-
</defs>
239-
</svg>
240-
<CountdownCircleTimer colors="url(#your-unique-id)">
241-
{({ remainingTime }) => remainingTime}
242-
</CountdownCircleTimer>
243-
```
244-
245-
### React - slide down time animation
246-
247-
<img src="https://user-images.githubusercontent.com/10707142/65963815-cfbdf380-e45b-11e9-809d-970174e88914.gif" width="200">
248-
249-
Check the [CodeSandbox](https://codesandbox.io/s/silly-night-d3s70?fontsize=14&hidenavigation=1&theme=dark) demo to find out how you can implement it yourself
250-
251-
### React - days, hours, minutes, seconds countdown
252-
253-
<img src="https://user-images.githubusercontent.com/10707142/80909463-efd2cf80-8d28-11ea-8592-a179f49ac4ba.gif" width="500">
254-
255-
Check the [CodeSandbox](https://codesandbox.io/s/musing-davinci-mqssz?fontsize=14&hidenavigation=1&theme=dark) demo for one possible solution

‎packages/mobile/README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,22 @@ React Native countdown timer component in a circle shape with color and progress
99

1010
<img src="https://user-images.githubusercontent.com/10707142/66097204-ca68c200-e59d-11e9-9b70-688409755aaa.gif" width="200"> <img src="https://user-images.githubusercontent.com/10707142/65935516-a0869280-e419-11e9-9bb0-40c4d1ef2bbe.gif" width="200"> <img src="https://user-images.githubusercontent.com/10707142/65963815-cfbdf380-e45b-11e9-809d-970174e88914.gif" width="200">
1111

12+
## Features
13+
1214
:zap: Performance optimized with single `requestAnimationFrame` loop to animate color and progress
1315
:rainbow: Transition between colors during the countdown
1416
:european_castle: Fully customizable content in the center of the circle
1517
:rocket: Support iOS and Android
1618

17-
## Installation
19+
## Install
1820

1921
```
2022
yarn add react-native-countdown-circle-timer
2123
```
2224

2325
This component has a peer dependency on `react-native-svg` to draw the countdown circle. `react-native-svg` has to be installed and linked into your project.
2426

25-
## Demo
27+
## Usage
2628

2729
### Component
2830

@@ -90,7 +92,7 @@ const {
9092

9193
Once the component is mounted the `duration` prop can be changed the the timer will respect the new duration. In case the new duration is bigger than the previous one then the timer will continue to the new duration. In case the new duration is smaller then the previous one then the timer will ne over. If you want to restart the timer when the duration changes then pass a new `key` prop to `CountdownCircleTimer` component and the timer will start over with the new values provided.
9294

93-
### Restart/Reset timer at any given time
95+
### Restart timer at any given time
9496

9597
Pass a `key` prop to `CountdownCircleTimer` and change the `key` when the timer should be restarted. Check [this demo](https://codesandbox.io/s/tender-bogdan-qd35m) to find out one possible implementation.
9698

@@ -187,6 +189,6 @@ Define the SVG gradient outside the Timer component and pass the gradient ID to
187189
</Defs>
188190
</Svg>
189191
<CountdownCircleTimer colors="url(#your-unique-id)">
190-
{({ remainingTime }) => remainingTime}
192+
{({ remainingTime }) => <Text>{remainingTime}</Text>}
191193
</CountdownCircleTimer>
192194
```

‎packages/web/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,19 @@ React countdown timer component in a circle shape with color and progress animat
99

1010
<img src="https://user-images.githubusercontent.com/10707142/66097204-ca68c200-e59d-11e9-9b70-688409755aaa.gif" width="200"> <img src="https://user-images.githubusercontent.com/10707142/65935516-a0869280-e419-11e9-9bb0-40c4d1ef2bbe.gif" width="200"> <img src="https://user-images.githubusercontent.com/10707142/65963815-cfbdf380-e45b-11e9-809d-970174e88914.gif" width="200">
1111

12+
## Features
13+
1214
:zap: Performance optimized with single `requestAnimationFrame` loop to animate color and progress
1315
:rainbow: Transition between colors during the countdown
1416
:european_castle: Fully customizable content in the center of the circle
1517

16-
## Installation
18+
## Install
1719

1820
```
1921
yarn add react-countdown-circle-timer
2022
```
2123

22-
## Demo
24+
## Usage
2325

2426
### Component
2527

@@ -90,7 +92,7 @@ The component and hook support [all modern browsers](https://caniuse.com/?search
9092

9193
Once the component is mounted the `duration` prop can be changed the the timer will respect the new duration. In case the new duration is bigger than the previous one then the timer will continue to the new duration. In case the new duration is smaller then the previous one then the timer will ne over. If you want to restart the timer when the duration changes then pass a new `key` prop to `CountdownCircleTimer` component and the timer will start over with the new values provided.
9294

93-
### Restart/Reset timer at any given time
95+
### Restart timer at any given time
9496

9597
Pass a `key` prop to `CountdownCircleTimer` and change the `key` when the timer should be restarted. Check [this demo](https://codesandbox.io/s/tender-bogdan-qd35m) to find out one possible implementation.
9698

0 commit comments

Comments
 (0)