Real-world applications often involve processing large volumes of data. For example, imagine a list of users, products, or posts that could grow into thousands or even millions of records. Loading all data at once is inefficient and can degrade application performance.

This is where pagination becomes important. Pagination allows you to fetch and display data in smaller chunks instead of loading everything at once. This improves performance, reduces server load, and provides a better user experience.

In this tutorial, we will learn how to implement pagination in MongoDB using Node.js. We will start from the basics, understand the core concepts, and then build a complete working example using Express and Mongoose.

What Is Pagination?

Pagination is a technique that divides large datasets into smaller, manageable units called pages. Instead of retrieving all records, you request only a specific subset based on page number and limit.

For example, instead of fetching 1000 users, you fetch:

• Page 1 → First 10 users
• Page 2 → Next 10 users

This approach ensures that your application remains fast and scalable.

How Pagination Works in MongoDB

MongoDB provides built-in methods that make pagination simple. The two most important concepts are:

• Limit: Defines how many documents to return.
• Skip: Defines how many documents to skip.

For example:

• limit(10) → Return 10 documents
• skip(10) → Skip first 10 documents

Together, these parameters enable fetching specific pages of data.

Project Structure

Before implementing pagination, it is important to organize the project properly. A clean structure helps separate concerns and keeps the application scalable.

project-root/
├── src/
│   ├── config/
│   │   └── db.js
│   ├── models/
│   │   └── user.model.js
│   ├── controllers/
│   │   └── user.controller.js
│   ├── services/
│   │   └── user.service.js
│   ├── routes/
│   │   └── user.routes.js
│   └── app.js
├── server.js
└── .env

This structure ensures that database logic, business logic, and routing are all clearly separated.

Step 1: Set Up the Database Connection

The database connection is configured inside the src/config/db.js file. This file is responsible for connecting your Node.js application to MongoDB.

const mongoose = require('mongoose');

const connectDB = async () => {
  try {
    await mongoose.connect(process.env.MONGO_URI);
    console.log('MongoDB Connected');
  } catch (error) {
    console.error(error.message);
    process.exit(1);
  }
};

module.exports = connectDB;

This setup ensures that your database connection is reusable and isolated from the rest of your application.

Step 2: Create the User Model

Next, we define a schema for our data inside the src/models/user.model.js file. This represents the structure of the data stored in MongoDB.

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  name: String,
  email: String
}, { timestamps: true });

module.exports = mongoose.model('User', userSchema);

This model will be used to perform database operations.

Step 3: Implement Pagination Logic in the Service Layer

Instead of placing logic inside controllers, we implement pagination inside the src/services/user.service.js file. This keeps our architecture clean and scalable.

const User = require('../models/user.model');

exports.getUsersWithPagination = async (page, limit) => {
  const skip = (page - 1) * limit;

  const users = await User.find()
    .skip(skip)
    .limit(limit);

  const total = await User.countDocuments();

  return {
    total,
    page,
    limit,
    users
  };
};

Here, we calculate how many records to skip based on the page number and limit. This is the core logic behind pagination.

Step 4: Create the Controller

The controller acts as a bridge between the request and the service layer. Inside the src/controllers/user.controller.js file, we handle incoming requests and return paginated data.

const userService = require('../services/user.service');

exports.getUsers = async (req, res, next) => {
  try {
    const page = parseInt(req.query.page) || 1;
    const limit = parseInt(req.query.limit) || 10;

    const result = await userService.getUsersWithPagination(page, limit);

    res.json(result);
  } catch (error) {
    next(error);
  }
};

This allows users to control pagination using query parameters.

Step 5: Define Routes

Routes define how API endpoints are exposed. Inside the src/routes/user.routes.js file, we connect the route to the controller.

const express = require('express');
const router = express.Router();
const userController = require('../controllers/user.controller');

router.get('/', userController.getUsers);

module.exports = router;

This makes the pagination API accessible via HTTP requests.

Step 6: Set Up the Express App

The Express application is configured inside the src/app.js file, where routes and middleware are registered.

const express = require('express');
const userRoutes = require('./routes/user.routes');

const app = express();

app.use(express.json());
app.use('/api/users', userRoutes);

module.exports = app;

Step 7: Start the Server

The main entry point of the application is the server.js file. It initializes the database and starts the server.

require('dotenv').config();
const app = require('./src/app');
const connectDB = require('./src/config/db');

connectDB();

app.listen(process.env.PORT || 5000, () => {
  console.log('Server running');
});

Testing the Pagination API

Once the server is running, you can test pagination using a browser or Postman.

Example request:

GET /api/users?page=1&limit=5

This will return the first 5 users. Changing the page number will fetch the next set of results.

Improving Pagination for Production

While skip and limit work well for small datasets, they become inefficient on large collections. In production systems, cursor-based pagination is a more efficient alternative.

You should also consider adding:

• Sorting for consistent results.
• Indexing for performance.
• Validation for query parameters.

These improvements make your API more robust and scalable.

Conclusion

In this tutorial, we explored how to implement pagination in MongoDB using Node.js. We first covered pagination, then built a scalable implementation using a clean architecture approach.

Pagination is an essential feature in modern applications, and mastering it will help you build efficient and user-friendly systems. By structuring your code properly and handling pagination at the service level, you ensure that your application remains maintainable as it grows.