diff --git a/README.md b/README.md
index a812c06211..8e36339e0d 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@
- [`useRaf`](./docs/useRaf.md) — re-renders component on each `requestAnimationFrame`.
- [`useInterval`](./docs/useInterval.md) — re-renders component on a set interval using `setInterval`.
- [`useSpring`](./docs/useSpring.md) — interpolates number over time according to spring dynamics.
- - [`useTimeout`](./docs/useTimeout.md) — returns true after a timeout.
+ - [`useTimeout`](./docs/useTimeout.md) — re-renders component after a timeout.
- [`useTimeoutFn`](./docs/useTimeoutFn.md) — calls given function after a timeout. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/animation-usetimeoutfn--demo)
- [`useTween`](./docs/useTween.md) — re-renders component, while tweening a number from 0 to 1. [![][img-demo]](https://codesandbox.io/s/52990wwzyl)
- [`useUpdate`](./docs/useUpdate.md) — returns a callback, which re-renders component when called.
diff --git a/docs/useTimeout.md b/docs/useTimeout.md
index 4c4c96e217..6c09e62c7d 100644
--- a/docs/useTimeout.md
+++ b/docs/useTimeout.md
@@ -1,15 +1,48 @@
# `useTimeout`
-Returns `true` after a specified number of milliseconds.
+Re-renders the component after a specified number of milliseconds.
+Provides handles to cancel and/or reset the timeout.
## Usage
```jsx
import { useTimeout } from 'react-use';
-const Demo = () => {
- const ready = useTimeout(2000);
+function TestComponent(props: { ms?: number } = {}) {
+ const ms = props.ms || 5000;
+ const [isReady, cancel] = useTimeout(ms);
+
+ return (
+
+ { isReady() ? 'I\'m reloaded after timeout' : `I will be reloaded after ${ ms / 1000 }s` }
+ { isReady() === false ? : '' }
+
+ );
+}
- return
Ready: {ready ? 'Yes' : 'No'}
;
+const Demo = () => {
+ return (
+
+
+
+
+ );
};
```
+
+## Reference
+
+```ts
+const [
+ isReady: () => boolean | null,
+ cancel: () => void,
+ reset: () => void,
+] = useTimeout(ms: number = 0);
+```
+
+- **`isReady`**_` :()=>boolean|null`_ - function returning current timeout state:
+ - `false` - pending re-render
+ - `true` - re-render performed
+ - `null` - re-render cancelled
+- **`cancel`**_` :()=>void`_ - cancel the timeout (component will not be re-rendered)
+- **`reset`**_` :()=>void`_ - reset the timeout
diff --git a/src/__stories__/useTimeout.story.tsx b/src/__stories__/useTimeout.story.tsx
index a393ee21f7..99fda16a66 100644
--- a/src/__stories__/useTimeout.story.tsx
+++ b/src/__stories__/useTimeout.story.tsx
@@ -3,10 +3,25 @@ import * as React from 'react';
import { useTimeout } from '..';
import ShowDocs from './util/ShowDocs';
-const Demo = () => {
- const ready = useTimeout(2e3);
+function TestComponent(props: { ms?: number } = {}) {
+ const ms = props.ms || 5000;
+ const [isReady, cancel] = useTimeout(ms);
+
+ return (
+
+ {isReady() ? "I'm reloaded after timeout" : `I will be reloaded after ${ms / 1000}s`}
+ {isReady() === false ? : ''}
+