Tutorials / Express /

Query Parameters in Express

Oct 25, 2019

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' }

Want to become your team's Express expert? There's no better way to really grok a framework than to write your own clone from scratch. In 15 concise pages, this tutorial walks you through how to write a simplified clone of Express called Espresso. Get your copy!

Espresso supports:

Route handlers, like `app.get()` and `app.post()`

Express-compatible middleware, like `app.use(require('cors')())`

Express 4.0 style subrouters

As a bonus, Espresso also supports async functions, unlike Express.

Get the tutorial and master Express today!

Did you find this tutorial useful? Say thanks by starring our repo on GitHub!

Query Parameters in Express

Objects and Arrays in Query Strings

More Express Tutorials