Query Parameters in Express

The query string portion of a URL is the part of the URL after the question mark ?. For example:

?answer=42

Each key=value pair is called a query parameter. If your query string has multiple query parameters, they're separated by &. For example, the below string has 2 query parameters, a and b.

?a=1&b=2

Express automatically parses query parameters for you and stores them on the request object as req.query.

const app = require('express')();

app.get('*', (req, res) => {
  req.query; // { a: '1', b: '2' }
  res.json(req.query);
});

const server = await app.listen(3000);
// Demo of making a request to the server
const axios = require('axios');
const res = await axios.get('http://localhost:3000/?a=1&b=2')

res.data; // { a: '1', b: '2' }

Objects and Arrays in Query Strings

If a query parameter appears multiple times in the query string, Express will group the values into an array. For example, given the below query string:

?color=black&color=yellow

Express will set req.query.color to an array ['black', 'yellow'].

const app = require('express')();

app.get('*', (req, res) => {
  req.query; // { color: ['black', 'yellow'] }
  res.json(req.query);
});

const server = await app.listen(3000);
// Demo of making a request to the server
const axios = require('axios');
const querystring = '?color=black&color=yellow';
const res = await axios.get('http://localhost:3000/' + querystring);

res.data; // { color: ['black', 'yellow'] }

If you use square brackets in a query string parameter, Express will parse that parameter as an object. For example, Express will parse the below query string into { shoe: { color: 'white' } }

?shoe[color]=white

This default behavior is often a nasty surprise and can cause security vulnerabilities. To prevent Express from parsing square brackets as object properties, you should set the query parser app setting to 'simple'.

const app = require('express')();

// Only parse query parameters into strings, not objects
app.set('query parser', 'simple');

app.get('*', (req, res) => {
  req.query; // { color: ['black', 'yellow'], 'shoe[color]': 'white' }
  res.json(req.query);
});

const server = await app.listen(3000);
// Demo of making a request to the server
const axios = require('axios');
const querystring = '?color=black&color=yellow&shoe[color]=white';
const res = await axios.get('http://localhost:3000/' + querystring);

res.data; // { color: ['black', 'yellow'], 'shoe[color]': 'white' }

---

---

More Express Tutorials

• How to Set Response Headers in Express
• Handle POST Form Data with Express JS
• What Does `app.use(express.json())` Do in Express?
• Handling POST Requests with Express
• What Does `app.use(express.static())` Do in Express?
• The `app.get()` Function in Express
• The `app.use()` Function in Express