JavaScript Promises for Beginners: A Complete Plain-English Guide

Introduction

If you’ve been learning JavaScript for a little while, you’ve probably run into a situation where your code does something unexpected — like trying to use data before it’s actually loaded. That’s where JavaScript promises come in. A promise is JavaScript’s way of saying, “Hey, I’ll give you a result eventually — I just need a moment.” Think of it like ordering food at a restaurant. You place your order, the kitchen gets to work, and the waiter promises to bring your meal when it’s ready. You don’t just stand at the counter and wait — you sit down, relax, and do other things until your food arrives. That’s exactly how JavaScript promises work. In this beginner-friendly guide, we’ll break down what promises are, why they exist, how to write them, and how to handle both success and failure — all without the confusing technical jargon. Whether you’re brand new to coding or just stuck on async JavaScript, this guide is written specifically for you.

Why JavaScript Needs Promises

To understand promises, you first need to understand a concept called asynchronous code. JavaScript runs one line at a time, from top to bottom. But some tasks — like fetching data from a server, reading a file, or waiting for a timer — take time to complete. Without a way to handle these delayed tasks, JavaScript would freeze up and wait for each slow task to finish before moving on. Imagine a web page that locked up every time it loaded an image. Nobody wants that. Before promises were introduced in ES6 (2015), developers used something called callbacks to handle async tasks. A callback is just a function you pass into another function to be called later. While callbacks work, they quickly become messy and hard to read — a problem developers call “callback hell.” Here’s what callback hell looks like: you have a function inside a function inside a function, all nested together like a confusing Russian doll. Promises were invented to solve this exact problem. They make async code cleaner, easier to read, and much easier to debug. They also gave JavaScript a foundation for the even cleaner async/await syntax that came later — but one step at a time!

Understanding the Three States of a Promise

Every JavaScript promise lives in one of three states at any given moment, and understanding these states is the key to mastering promises. The first state is Pending. This is the starting state. The promise has been created, but the result isn’t available yet. Think of it as your restaurant order being prepared in the kitchen. The second state is Fulfilled (also called resolved). This means the async task completed successfully and the promise has a result value you can use. Your food arrived at the table — success! The third state is Rejected. This means something went wrong. The async task failed and the promise has a reason (an error) explaining what happened. Think of the kitchen running out of ingredients. Once a promise moves from Pending to either Fulfilled or Rejected, it stays in that final state forever. It can never go back to Pending or switch from Fulfilled to Rejected. This predictability is one of the reasons promises are so useful. Here’s the most basic way to create a promise in JavaScript: const myPromise = new Promise((resolve, reject) => { const success = true; if (success) { resolve('It worked!'); } else { reject('Something went wrong.'); } }); In this example, you create a new Promise and pass it a function with two parameters: resolve and reject. You call resolve() when things go well, and reject() when they don’t. Simple as that.

How to Use .then(), .catch(), and .finally()

Creating a promise is only half the story. You also need to know how to consume a promise — that is, how to use its result once it’s ready. JavaScript gives you three built-in methods for this: .then(), .catch(), and .finally(). The .then() method runs when a promise is fulfilled. You pass it a function, and that function receives the resolved value as its argument. For example: myPromise.then((result) => { console.log(result); }); This would print It worked! to the console. The .catch() method runs when a promise is rejected. It catches errors so your program doesn’t crash unexpectedly: myPromise.catch((error) => { console.log(error); }); You can also chain these together, which is where promises really shine: myPromise .then((result) => { console.log('Success:', result); }) .catch((error) => { console.log('Error:', error); }) .finally(() => { console.log('All done, no matter what!'); }); The .finally() method always runs at the end, whether the promise was fulfilled or rejected. It’s great for cleanup tasks, like hiding a loading spinner on a web page. One of the most powerful features of promises is chaining. Because .then() itself returns a new promise, you can chain multiple .then() calls together in a readable, top-to-bottom sequence — completely avoiding that callback hell we talked about earlier. Each .then() passes its return value to the next one in the chain, making complex async workflows surprisingly easy to follow.

Frequently Asked Questions

What is the difference between a promise and a callback in JavaScript?

Both promises and callbacks are ways to handle asynchronous code in JavaScript, but they work very differently. A callback is a function you pass as an argument to another function, which then calls it when the async task is done. While callbacks are simple for small tasks, they become very hard to manage when you have multiple async operations that depend on each other — leading to deeply nested code known as callback hell. A promise is an object that represents the eventual result of an async operation. Instead of nesting functions inside functions, you chain .then() calls in a flat, readable sequence. Promises also have built-in error handling with .catch(), making them much more reliable and maintainable than callbacks for complex applications. In short, callbacks came first, promises made async code cleaner, and then async/await (built on top of promises) made it even cleaner still.

What is async/await and how does it relate to promises?

Async/await is a newer JavaScript syntax (introduced in ES2017) that lets you write promise-based code in a way that looks and reads almost like regular synchronous code. Under the hood, async/await is just promises with a friendlier face. When you mark a function with the async keyword, it automatically returns a promise. Inside that function, you can use the await keyword to pause execution until a promise resolves, without blocking the rest of your program. For example: async function getData() { const result = await myPromise; console.log(result); } This does exactly the same thing as using .then(), but it reads like normal, top-to-bottom code. Most modern JavaScript developers prefer async/await for readability, but it’s important to learn promises first because async/await is built directly on top of them. You’ll also still encounter .then() and .catch() frequently in real-world codebases.

How do I handle multiple promises at the same time?

Sometimes you need to run several async operations at once and wait for all of them to finish before doing something with the results. JavaScript provides Promise.all() for exactly this purpose. You pass it an array of promises, and it returns a single promise that resolves when every promise in the array has resolved. For example: Promise.all([promise1, promise2, promise3]) .then((results) => { console.log(results); }) .catch((error) => { console.log('One failed:', error); }); The results variable will be an array of each resolved value, in the same order as your original array. If even one promise in the array rejects, Promise.all() immediately rejects with that error. If you want to wait for all promises to settle regardless of success or failure, use Promise.allSettled() instead. And if you only care about the fastest promise to resolve, Promise.race() is your tool. These utility methods make handling complex async workflows much more manageable.

Conclusion

JavaScript promises might seem intimidating at first, but once you get the hang of the three states — pending, fulfilled, and rejected — and learn how to use .then(), .catch(), and .finally(), you’ll realize they make async code so much easier to work with. You now understand why promises were invented, how to create one from scratch, how to consume a promise’s result, and how to handle errors gracefully. You’ve also gotten a peek at async/await and Promise.all(), two tools you’ll use constantly as you grow as a developer. The best way to solidify this knowledge is to practice. Try writing a simple promise that simulates a data fetch using setTimeout, then chain some .then() calls together. Make it fail on purpose and catch the error. Once promises feel natural, move on to async/await — you’ll be surprised how quickly it clicks when you have this foundation. Keep coding, keep experimenting, and remember: every professional JavaScript developer was once exactly where you are right now.