Charset negotiation
A route supports several text encodings and wants to select the first compatible option advertised by the client.
Express.js · Pipe
req.acceptsCharsets
Checks candidate character sets against the request’s Accept-Charset header. It returns the first accepted candidate or false when none is acceptable.
How it works
Call this request method with one or more candidate character sets. Express compares them with the request's Accept-Charset header and returns the first accepted candidate, or false when no candidate matches.
Syntax
req.acceptsCharsets(charset)Parameters
| Name | Type | Description |
|---|---|---|
charset | String | String[] | One or more character sets to test against the request's Accept-Charset header. |
Returns
String | false
Key points
- Provide either one charset string or an array containing multiple candidate character sets.
- The result is the first supplied candidate that the request accepts.
- Negotiation is driven by the incoming Accept-Charset header.
- The documented example demonstrates weighted charset preferences, with utf-8 preferred over iso-8859-1.
- When the requested charset is not accepted, the method returns false rather than a matching name.
Common mistakes
- Check explicitly for false before using the result; an unmatched request does not produce a charset string.
Example: Choose an accepted charset
const express = require('express');
const app = express();
app.get('/', (req, res) => {
const charset = req.acceptsCharsets('utf-8', 'iso-8859-1');
if (!charset) return res.sendStatus(406);
res.type('text').send(`Selected charset: ${charset}`);
});
app.listen(3000);Run the app and send an Accept-Charset header such as utf-8, iso-8859-1;q=0.5 to see the first accepted option.
When to use it
Negotiation failure handling
An endpoint must reject requests when none of its supported character sets is accepted.
Request compatibility checks
Middleware needs to branch behavior based on whether a request accepts a particular charset.
Interview questions
QWhat does req.acceptsCharsets() return?
It accepts a string or an array of strings representing candidate character sets. Express evaluates those candidates against the request's Accept-Charset header and returns the first accepted one, or false if there is no match.
Follow-up: How should a route respond when no candidate is acceptable? Treat the false result as negotiation failure and commonly return HTTP 406 Not Acceptable.
QWhich request header controls the result?
The method uses the request's Accept-Charset header to determine whether candidates are acceptable. Quality values in that header influence the negotiation, as shown by the documented example with utf-8 and iso-8859-1.
Follow-up: What header should a client send to influence this method? It should send Accept-Charset with the preferred character sets and optional quality weights.
QHow can callers provide multiple choices?
The method can be called with multiple charset arguments, such as utf-8 followed by iso-8859-1. The returned value identifies the first accepted candidate from the supplied choices.
Follow-up: What should be avoided in new code? Avoid the deprecated singular req.acceptsCharset() alias; use the plural method instead.
Related
req.acceptsreq.acceptsEncodingsreq.acceptsLanguagesreq.is