useConditionalTimeout.md

useConditionalTimeout

An async-utility hook that accepts a callback function, a delay time (in milliseconds) and a condition, then delays the execution of the given function by the defined time when the condition is verified.

💡 Why?

• to start a timeout only after a given condition is verified;
• takes care of performing the given callback regardless the component re-renders;
• cancels the timeout when component unmount (or not, depends by the defined options) and/or the given condition verifies;

Basic Usage:

import { useState } from 'react';
import { Button } from 'beautiful-react-ui';
import { useConditionalTimeout } from 'beautiful-react-hooks'; 


const ConditionalDelayedContentComponent = () => {
  const [condition,setCondition] = useState(false);
  const [showContent, setShowContent] = useState(false);
  useConditionalTimeout(()=>{ setShowContent(true) }, 2000, condition);
    
  return (
    <DisplayDemo>
      <Button color="primary" icon="clock" onClick={()=>setCondition(true)}> Start a 2 seconds timeout</Button>
      {showContent && <div style={{fontSize: '3rem'}}>🕰</div>}   
    </DisplayDemo>) 
};

<ConditionalDelayedContentComponent />

State & clear method:

The hook returns the state of the timeout (a boolean, cleared/not cleared) and a method to possibly clear it.

import {useState} from 'react';
import { Button, Paragraph } from 'beautiful-react-ui';
import { useConditionalTimeout } from 'beautiful-react-hooks'; 

const ConditionalDelayedContentComponent = () => {
  const [condition,setCondition] = useState(false);
  const [showContent, setShowContent] = useState(false);
  const [isCleared, clearTimeoutRef] = useConditionalTimeout(()=>{
    setShowContent(true)
  }, 5000, condition);

  return (
    <DisplayDemo>
      <Paragraph>Content will show after 5 second starting from the following button click</Paragraph>
      <Button color="primary" icon="clock" onClick={()=>setCondition(true)}>Start a 5 seconds timeout</Button>
      {showContent && <div style={{fontSize: '3rem'}}>🕰</div>} 
      {!isCleared && <Button onClick={clearTimeoutRef}>Cancel timeout</Button>}
      {isCleared && <Paragraph>Cleared</Paragraph>}  
    </DisplayDemo>)
};

<ConditionalDelayedContentComponent />

Options:

useConditionalTimeout might accept a options object provided as eventual parameter.

cancelOnUnmount:

Defines whether the timeout should be cleared on unmount.

default: true

import { useState } from 'react'; 
import { Button } from 'beautiful-react-ui';
import { useConditionalTimeout } from 'beautiful-react-hooks'; 

const ConditionalDelayedContentComponent = () => {
  const [condition,setCondition] = useState(false);
  const [showContent, setShowContent] = useState(false);
  const options = { cancelOnUnmount: false };
    
  useConditionalTimeout(()=>{setShowContent(true)}, 5000, condition, options);
    
  return (
    <DisplayDemo>
      <Button color="primary" icon="clock" onClick={()=>setCondition(true)}>Start a 5 seconds timeout</Button>
      {showContent && <div style={{fontSize: '3rem'}}>🕰</div>}   
    </DisplayDemo>)
};

<ConditionalDelayedContentComponent />

cancelOnConditionChange:

Defines whether the timeout should be cleared when the condition change.

In this example nothing will happen because when clicking on the button, 2 instance of useConditionalTimeout will be performed, and one of them will change the condition.

default: true

import { useState } from 'react';
import { Button } from 'beautiful-react-ui';
import { useConditionalTimeout } from 'beautiful-react-hooks'; 

const ConditionalDelayedContentComponent = () => {
  const [condition,setCondition] = useState(false);
  const [showContent, setShowContent] = useState(false);
   
  useConditionalTimeout(()=>{setShowContent(true)}, 5000, condition);
  useConditionalTimeout(()=>{setCondition(false)}, 2000, condition);

   return (
    <DisplayDemo>
      <Button color="primary" icon="clock" onClick={()=>setCondition(true)}>Start a 5 seconds timeout</Button>
      {showContent && <div style={{fontSize: '3rem'}}>🕰</div>}   
    </DisplayDemo>)
};

<ConditionalDelayedContentComponent />

Mastering the hooks

✅ When to use

• If there's the necessity to run a callback after a certain time and only when a certain condition is verified.