sleep()

sleep(ms): Promise<void>

Pauses execution for a specified duration.

---

Parameters

ms: number

Duration to sleep in milliseconds (must be non-negative).

---

Returns: Promise<void>

Promise that resolves after the specified duration.

---

Throws

RangeError If ms is negative.

---

Since

2.0.0

---

Also known as

delay (es-toolkit) · sleep (Radashi, Effect, Modern Dash, Antfu) · ❌ (Lodash, Remeda, Ramda)

---

Example

await sleep(1000);
console.log('1 second later');

// Sequential delays
for (const item of items) {
  await process(item);
  await sleep(100);
}

---

How it works?

Pauses execution for a specified duration. Returns a Promise that resolves after the delay.

Usage

Sequential Delays

Rate limiting between operations.

---

Use Cases

Delay async execution 📌

Pause async execution for a specific duration. Essential for throttling, polling intervals, or simulating latency in tests.

#delay#async#pause#sleep#throttle#polling#performance

await sleep(1000); // Wait 1 second
await fetchData();

Respect API rate limits

Introduce delays between batch operations to avoid hitting rate limits.

#respect#rate-limits#throttle#batch#delays#API#scripts#ci/cd

for (const item of batch) {
  await sendRequest(item);
  await sleep(100); // 100ms between requests
}

Simulate network latency

Add artificial delays in development/testing environments.

#simulate#latency#network#testing#development#delays

if (isDev) {
  await sleep(500); // Simulate slow network
}
return mockData;

Animate sequential UI elements

Stagger entrance animations for list items or cards. Perfect for loading sequences and reveal animations.

#animate#sequential#stagger#UI#entrance#design system#loading

const staggerReveal = async (elements: HTMLElement[]) => {
  for (const el of elements) {
    el.classList.add("visible");
    await sleep(80); // 80ms stagger between each item
  }
};

staggerReveal([...document.querySelectorAll<HTMLElement>(".card")]);

Implement a countdown timer

Display a countdown before starting an action or game round. Essential for game lobbies, quiz timers, and timed events.

#countdown#timer#seconds#display#gaming#loading

const countdown = async (seconds: number, onTick: (remaining: number) => void) => {
  for (let i = seconds; i > 0; i--) {
    onTick(i);
    await sleep(1000);
  }
  onTick(0);
};

await countdown(3, (n) => {
  display.textContent = n === 0 ? "Go!" : String(n);
});
startGame();

Wait for CSS transition to complete

Pause execution until a CSS transition finishes before proceeding. Essential for sequencing JS logic after CSS animations.

#CSS#transition#wait#animation#duration#design system

const collapsePanel = async (panel: HTMLElement) => {
  panel.classList.add("collapsing");
  await sleep(300); // Match CSS transition-duration
  panel.classList.remove("collapsing");
  panel.classList.add("collapsed");
  panel.style.display = "none";
};

Delay tooltip appearance

Show a tooltip only after the user hovers for a minimum duration. Prevents tooltips from flashing during quick mouse movements.

#tooltip#delay#hover#show#UX#design system#a11y

let isStillHovering = false;

element.addEventListener("mouseenter", async () => {
  isStillHovering = true;
  await sleep(400); // 400ms hover delay
  if (isStillHovering) {
    showTooltip(element);
  }
});

element.addEventListener("mouseleave", () => {
  isStillHovering = false;
  hideTooltip();
});