Table of Contents
The query string is a part of the URL (Uniform Resource Locator) that assigns values to specific parameters.
While developing our web apps, we might use query string values to dynamically render a part of the user interface with specific parameters.
For instance, I provide a shareable link with the Timezone Checker web app, including the user configuration.
Plain Text
https://timezonechecker.app/embed?timeFormat=24h&timezones=Europe/London,Europe/Nicosia&Europe/Rome=luca&Europe/London=lars,erik,john
The query string parameters and values are (parameter=value):
Plain Text
timeFormat=24h
timezones=Europe/London,Europe/Nicosia
Europe/Rome=luca
Europe/London=lars,erik,john
In Next.js with App Router, there are different components: client components, pages, layouts, and routes.
Let’s see how we can read the query strings in each one of those.
Client components
In a client component you can use the React Hooks
useSearchParams
to return a read only version of the URLSearchParams JavaScript interface.TypeScript
'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const timeFormat = searchParams.get('timeFormat')
// URL -> `/embed?timeFormat=24h`
// `timeFormat` -> '24h'
return <>Time format: {timeFormat}</>
}
You can use the URLSearchParams method has() to determine if a query string param is present or not.
URL | searchParams.has(”timeFormat”) |
/embed | false |
/embed?timeFormat=24h | true |
The URLSearchParams interface has other read-only methods, like getAll(), keys(), values(), entries(), forEach(), and toString().
Pages
In pages, you can use the searchParams prop to access the query string params.
In this case, an object is returned.
src/app/embed/page.tsx
TypeScript
export default function EmbedPage({ searchParams }) {
// URL -> `/embed?timeFormat=24h`
// searchParams['timeFormat'] -> '24h'
return <>Time format: {searchParams['timeFormat']}</>
}
Routes
In routes (backend endpoints), you can access the URLSearchParams interface this way:
src/app/api/embed/route.ts
TypeScript
import { NextRequest, NextResponse } from "next/server";
export async function GET(req: NextRequest) {
// URL -> `/api/embed?timeFormat=24h`
const timeFormat = req.nextUrl.searchParams.get("timeFormat")
return NextResponse.json(
{ timeFormat },
{ status: 200 }
);
}
Layouts
In layouts, you cannot access the query string params. Instead, access them from the pages or client components, rendered inside the layout.
Conclusion
Query strings are the comfortable way to save and transmit data into the URL, to allow the users to easily share configurations via the URL, and send data from the client to the server.
Ship your startup in days and start selling.
Save weeks of coding with the #1 Next.js Startup and Chrome Extension Boilerplate. Made by a maker for makers.