How to Use express.urlencoded Middleware in Express.js

Use express.urlencoded middleware in Express.js to parse incoming requests with URL-encoded payloads, typically from HTML forms. Add it to your app with app.use(express.urlencoded({ extended: false })) to access form data via req.body.

Syntax

The express.urlencoded middleware parses incoming requests with URL-encoded payloads. It takes an options object where extended controls the parsing method.

• extended: false uses the built-in querystring library to parse simple key-value pairs.
• extended: true uses the qs library to parse nested objects.

javascript

app.use(express.urlencoded({ extended: false }))

Example

This example shows a simple Express server that uses express.urlencoded to parse form data sent via POST. The server responds with the parsed data from req.body.

javascript

import express from 'express';

const app = express();
const port = 3000;

// Use express.urlencoded middleware to parse URL-encoded bodies
app.use(express.urlencoded({ extended: false }));

app.post('/submit', (req, res) => {
  // Access parsed form data from req.body
  res.send(`Received name: ${req.body.name}, age: ${req.body.age}`);
});

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});

Output

Server running on http://localhost:3000

When POSTing form data name=Alice&age=30 to /submit, response: Received name: Alice, age: 30

Common Pitfalls

Common mistakes when using express.urlencoded include:

• Not adding the middleware before route handlers, so req.body is undefined.
• Setting extended incorrectly for your data structure needs.
• Confusing express.urlencoded with express.json which parses JSON payloads.

Always add express.urlencoded early in your middleware stack to parse form data correctly.

javascript

/* Wrong: middleware added after route */
app.post('/submit', (req, res) => {
  res.send(req.body); // undefined
});
app.use(express.urlencoded({ extended: false }));

/* Right: middleware added before route */
app.use(express.urlencoded({ extended: false }));
app.post('/submit', (req, res) => {
  res.send(req.body); // parsed data
});

Quick Reference

• express.urlencoded({ extended: false }): Parse URL-encoded data with simple key-value pairs.
• express.urlencoded({ extended: true }): Parse URL-encoded data with nested objects.
• Add middleware before routes to access req.body.
• Use for HTML form submissions with application/x-www-form-urlencoded content type.

Key Takeaways

Add express.urlencoded middleware early to parse URL-encoded form data into req.body.

Use extended: false for simple data, extended: true for nested objects.

express.urlencoded only parses URL-encoded data, not JSON.

Without this middleware, req.body will be undefined for form submissions.

It is essential for handling HTML form POST requests in Express.