Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
react-countdown
Advanced tools
react-countdown - npm Package Compare versions
Comparing version 2.3.2 to 2.3.3
| { | ||
| "name": "react-countdown", | ||
| "version": "2.3.2", | ||
| "version": "2.3.3", | ||
| "description": "A customizable countdown component for React.", | ||
@@ -38,3 +38,4 @@ "main": "./dist/index.js", | ||
| "prettier": "prettier --write ./src/**/*.{ts,tsx}", | ||
| "test": "jest --coverage", | ||
| "test": "jest", | ||
| "test:coverage": "jest --coverage", | ||
| "test:e2e": "yarn start-server-and-test test:e2e:server http://localhost:1234 \"cypress run\"", | ||
@@ -41,0 +42,0 @@ "test:e2e:clean": "rm -rf ./e2e/dist", |
@@ -1,2 +0,2 @@ | ||
| # React <Countdown /> [![npm][npm]][npm-url] [](https://travis-ci.com/ndresx/react-countdown) [](https://coveralls.io/github/ndresx/react-countdown?branch=master) | ||
| # React <Countdown /> [![npm][npm]][npm-url] [](https://github.com/ndresx/react-countdown/actions/workflows/main.yml) [](https://coveralls.io/github/ndresx/react-countdown?branch=master) | ||
| A customizable countdown component for React. | ||
@@ -10,2 +10,3 @@ | ||
| * [Helpers](#helpers) | ||
| * [FAQ](#faq) | ||
| * [Contributing](#contributing) | ||
@@ -35,3 +36,3 @@ * [License](#license) | ||
| ### Basic Usage | ||
| A very simple and minimal example of how to set up a countdown which counts down from 10 seconds. | ||
| A very simple and minimal example of how to set up a countdown that counts down from 10 seconds. | ||
| ```js | ||
@@ -50,3 +51,3 @@ import React from 'react'; | ||
| ### Custom & Conditional Rendering | ||
| In case you want to change the output of the component, or want to signal that the countdown's work is done, you can do this by either using the [`onComplete`](#oncomplete) callback, a | ||
| In case you want to change the output of the component or want to signal that the countdown's work is done, you can do this by either using the [`onComplete`](#oncomplete) callback, a | ||
| custom [`renderer`](#renderer), or by specifying a React child within `<Countdown></Countdown>`, which will only be shown once the countdown is complete. | ||
@@ -130,4 +131,4 @@ | ||
| |:--|:--:|:-----:|:----------| | ||
| |[**date**](#date)|<code>Date|string|number</code>|`required`|Date or timestamp in the future| | ||
| |[**key**](#key)|<code>string|number</code>|`undefined`|React [**key**](https://reactjs.org/docs/lists-and-keys.html#keys); can be used to restart the countdown| | ||
| |[**date**](#date)|<code>Date|string|number</code>|required|[`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) or timestamp in the future| | ||
| |[**key**](#key)|<code>string|number</code>|`undefined`|React [`key`](https://reactjs.org/docs/lists-and-keys.html#keys); can be used to restart the countdown| | ||
| |[**daysInHours**](#daysinhours)|`boolean`|`false`|Days are calculated as hours| | ||
@@ -160,4 +161,4 @@ |[**zeroPadTime**](#zeropadtime)|`number`|`2`|Length of zero-padded output, e.g.: `00:01:02`| | ||
| ### `key` | ||
| This is one of React's internal component props and is used to identify the component. However, we can leverage this behavior and use it to, for example, restart the countdown by | ||
| passing in a new `string` or `number`. | ||
| This is one of React's internal component props to help identify elements throughout the reconciliation process. It can be used to restart the countdown by | ||
| passing in a new `string` or `number` value. | ||
@@ -177,3 +178,3 @@ Please see [official React docs](https://reactjs.org/docs/lists-and-keys.html#keys) for more information about keys. | ||
| ### `zeroPadDays` | ||
| Defaults to `zeroPadTime`. Works the same way as [`zeroPadTime`](#zeropadtime) does, just for days. | ||
| Defaults to `zeroPadTime`. It works the same way as [`zeroPadTime`](#zeropadtime) does, just for days. | ||
@@ -186,3 +187,3 @@ ### `intervalDelay` | ||
| ### `precision` | ||
| In certain cases, you might want to base off the calculations on a millisecond basis. The `precision` prop, which defaults to `0`, can be used to refine this calculation. While the default value simply strips the milliseconds part (e.g.: `10123`ms => `10000`ms), a precision of `3` leads to `10123`ms. | ||
| In certain cases, you might want to base off the calculations on a millisecond basis. The `precision` prop, which defaults to `0`, can be used to refine this calculation. While the default value simply strips the milliseconds part (e.g., `10123`ms => `10000`ms), a precision of `3` leads to `10123`ms. | ||
@@ -197,3 +198,3 @@ ### `autoStart` | ||
| > Please note that the [`children`](#children) prop will be ignored if `overtime` is `true`. | ||
| > Please note that the [`children`](#children) prop will be ignored if `overtime` is `true`. Also, when using a custom [`renderer`](#renderer), you'll have to check one of the [render props](#render-props), e.g., `total`, or `completed`, to render the overtime output. | ||
@@ -235,22 +236,22 @@ ### `children` | ||
| ### `onMount` | ||
| `onMount` is a callback and triggered when the countdown mounts. It receives the time delta object, which is returned by [`calcTimeDelta`](#calctimedelta). | ||
| `onMount` is a callback and triggered when the countdown mounts. It receives a [time delta object](#calctimedelta) as the first argument. | ||
| ### `onStart` | ||
| `onStart` is a callback and triggered whenever the countdown is started (including first-run). It receives the time delta object, which is returned by [`calcTimeDelta`](#calctimedelta). | ||
| `onStart` is a callback and triggered whenever the countdown is started (including first-run). It receives a [time delta object](#calctimedelta) as the first argument. | ||
| ### `onPause` | ||
| `onPause` is a callback and triggered every time the countdown is paused. It receives the time delta object, which is returned by [`calcTimeDelta`](#calctimedelta). | ||
| `onPause` is a callback and triggered every time the countdown is paused. It receives a [time delta object](#calctimedelta) as the first argument. | ||
| ### `onStop` | ||
| `onStop` is a callback and triggered every time the countdown is stopped. It receives the time delta object, which is returned by [`calcTimeDelta`](#calctimedelta). | ||
| `onStop` is a callback and triggered every time the countdown is stopped. It receives a [time delta object](#calctimedelta) as the first argument. | ||
| ### `onTick` | ||
| `onTick` is a callback and triggered every time a new period is started, based on what the [`intervalDelay`](#intervaldelay)'s value is. It only gets triggered when the countdown's [`controlled`](#controlled) prop is set to `false`, meaning that the countdown has full control over its interval. It receives the time delta object, which is returned by [`calcTimeDelta`](#calctimedelta). | ||
| `onTick` is a callback and triggered every time a new period is started, based on what the [`intervalDelay`](#intervaldelay)'s value is. It only gets triggered when the countdown's [`controlled`](#controlled) prop is set to `false`, meaning that the countdown has full control over its interval. It receives a [time delta object](#calctimedelta) as the first argument. | ||
| ### `onComplete` | ||
| `onComplete` is a callback and triggered whenever the countdown ends. In contrast to [`onTick`](#ontick), the [`onComplete`](#oncomplete) callback gets also triggered in case [`controlled`](#controlled) is set to `true`. It receives the time delta object, which is returned by [`calcTimeDelta`](#calctimedelta). | ||
| `onComplete` is a callback and triggered whenever the countdown ends. In contrast to [`onTick`](#ontick), the [`onComplete`](#oncomplete) callback also gets triggered in case [`controlled`](#controlled) is set to `true`. It receives a [time delta object](#calctimedelta) as the first argument and a `boolean` as a second argument, indicating whether the countdown transitioned into the completed state (`false`) or completed on start (`true`). | ||
| ## API Reference | ||
| The countdown component exposes a simple API through the `getApi()` function that can be accessed via component `ref`. It is also part (`api`) of the render props passed into [`renderer`](#renderer) if needed. | ||
| The countdown component exposes a simple API through the `getApi()` function that can be accessed via component `ref`. It is also part (`api`) of the [render props](#render-props) passed into [`renderer`](#renderer) if needed. Here's an [example](https://github.com/ndresx/react-countdown/blob/master/examples/src/CountdownApi.tsx) of how to use it. | ||
@@ -286,3 +287,3 @@ ### `start()` | ||
| ### `zeroPad(value, [length = 2])` | ||
| The `zeroPad` function works similarly to other well-known pad-functions and takes two arguments into account. A `value` which can be a `string` or `number`, as well as a `length` parameter which defaults to `2` as you are most likely only going to use this function if you actually want to pad one of your values. Either returns a `number` if `length` equals `0`, or the zero-padded `string`. | ||
| The `zeroPad` function transforms and returns a given `value` with padded zeros depending on the `length`. The `value` can be a `string` or `number`, while the `length` parameter can be a `number`, defaulting to `2`. Returns the zero-padded `string`, e.g., `zeroPad(5)` => `05`. | ||
@@ -305,4 +306,6 @@ ```js | ||
| This function accepts two arguments in total; only the first one is required. | ||
| The `total` value is the absolute time difference in milliseconds, whereas the other time-related values contain their relative portion of the current time difference. The `completed` value signalizes whether the countdown reached its initial end or not. | ||
| The `calcTimeDelta` function accepts two arguments in total; only the first one is required. | ||
| **`date`** | ||
@@ -326,3 +329,3 @@ Date or timestamp representation of the end date. See [`date`](#date) prop for more details. | ||
| - **`overtime = false`** | ||
| Defines whether the time delta can go into [`overtime`](#overtime) and become negative or not. When set to `true`, the `total` could become negative at which point `completed` will still be set to `true`. | ||
| Defines whether the time delta can go into [`overtime`](#overtime) and become negative or not. When set to `true`, the `total` could become negative, at which point `completed` will still be set to `true`. | ||
@@ -353,2 +356,21 @@ <a name="formattimedelta"></a> | ||
| ## FAQ | ||
| ### Why does my countdown reset on every re-render? | ||
| A common reason for this is that the [`date`](#date) prop gets passed directly into the component without persisting it in any way. | ||
| In order to avoid this from happening, it should be stored in a place that persists throughout lifecycle changes, for example, in the component's local `state`. | ||
| ### Why aren't my values formatted when using the custom [`renderer`](#renderer)? | ||
| The [`renderer`](#renderer) callback gets called with a [time delta object](#calctimedelta) that also consists of a `formatted` object which holds these formatted values. | ||
| ### Why do I get this error `"Warning: Text content did not match..."`? | ||
| This could have something to do with server-side rendering and that the countdown already runs on the server-side, resulting in a timestamp discrepancy between the client and the server. In this case, it might be worth checking https://reactjs.org/docs/dom-elements.html#suppresshydrationwarning. | ||
| Alternatively, you could try to set [`autoStart`](#autostart) to `false` and start the countdown through the [API](#api-reference) once it's available on the client. Here are some related [issues](https://github.com/ndresx/react-countdown/issues/152) that might help in fixing this problem. | ||
| ## Contributing | ||
@@ -355,0 +377,0 @@ |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by3.25%
64925
- Number of lines in readme file
- increased by6.27%
373
No dependency changes